{
  "swagger": "2.0",
  "info": {
    "title": "app2email WhatsApp API",
    "version": "1.4.0",
    "description": "Send WhatsApp **template messages** from your own systems (n8n, Zapier, Make, Power Automate, scripts, AI agents) through your app2email WhatsApp number.\n\n**Address:** every request includes the full WhatsApp number you send *from*, digits only: `https://api.app2email.com/v1/{number}/...`\n\n**Authentication:** the API key from https://www.app2email.com/dashboard/apikey, as `X-API-KEY: a2en_...` or `Authorization: Bearer a2en_...`. Keep the key on a server - do not put it in a web page. A key has **scopes**: `messages:send` (send, media upload, cancel a broadcast, conversation owner, approvals), `messages:read` (messages, conversations, broadcasts, usage, stats, templates, request log, contacts, stored media), `dnc:manage` (Do Not Call list, compliance export), `webhooks:manage`, `templates:manage` (templates and flows: create, edit, delete, archive, insights; each change applies to every number of the WhatsApp Business Account), `settings:manage` (auto reply, email forwarding, opt-ins, the number's settings), `contacts:manage` (contacts, segments, consent records), `calls:manage` (WhatsApp Calling), `bookings:manage` (appointment bookings, the booking settings, sending a Flow; the booking reads also work with `messages:read`), `submissions:manage` (Submit-Info: forms, submissions, the inbox team, automations and connections), `tickets:manage` (event tickets: events, ticket types, orders, refunds, tickets, check-in, promo codes), or `*` for full access. The Default key (the key made before keys with permissions existed) has `messages:send`, `messages:read`, `dnc:manage` and `webhooks:manage` only - creating templates and changing settings need a key created with Full access. A call the key may not make answers 403 `insufficient_scope`. A key can also be limited to some IP addresses, or expire. `GET /v1/{number}/me` checks a key and shows its name, scopes and limits.\n\n**Rate limit:** every call counts against its key (calls without a key: against the IP address). Each answer has the headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (seconds until full again) and `X-RateLimit-Policy`. Over the limit: 429 `rate_limited` with a `Retry-After` header and `error.retry_after_seconds`. Wait, then send again (`limits.rate_limit_mode` in GET /me is `enforce`).\n\n**Empty fields:** a field with no value is left out of the answer rather than sent as `null`, in API answers and in webhook events alike.\n\n**Errors:** every error is `{\"success\": false, \"request_id\", \"error\": {\"code\", \"message\", \"how_to_fix\", \"documentation_url\", \"is_retriable\", \"retry_after_seconds\"?, \"details\"?, \"example_request\"?, \"whatsapp_error\"?}}`. Decide by `code`. `is_retriable` is true when the same request can work later unchanged (limits, caps, trouble on our side or WhatsApp's); `retry_after_seconds` says how long to wait when it is known.\n\n**Request ID:** every answer, success or error, has a `request_id`. Quote it to support. `GET /v1/{number}/requests/{request_id}` shows what was logged for it (errors and requests that change something, kept 30 days).\n\n**Plans:** every call, reading as well as sending, needs a paid plan (Standard, Professional, Team, Agency or Agent/Developer; 403 `plan_not_allowed`) and a LIVE service (403 `service_not_live`).\n\n**For AI agents:** MCP server `https://api.app2email.com/mcp` (Streamable HTTP, the same `Authorization: Bearer` key, 189 tools that map to the calls below: https://www.app2email.com/docs/api/mcp). No account yet: an agent can create one for a person with the Management MCP server `https://api.app2email.com/mcp/manage` (`create_account`, no key; the person then confirms the e-mail, connects WhatsApp and chooses a plan): https://www.app2email.com/docs/api/agents. A2A agent: `GET https://api.app2email.com/.well-known/agent-card.json`, `POST /a2a/v1`. `GET https://api.app2email.com/health` (no key) reports the service status.\n\n**Request format:** the same as WhatsApp Cloud API template messages (`to`, `type: \"template\"`, `template.name`, `template.language.code`, `template.components`). Give one value per placeholder (`{{1}}`, `{{2}}`, ... or named placeholders with `parameter_name`).\n\n**Free-form replies:** `\"type\": \"text\" | \"image\" | \"video\" | \"document\"` sends a normal message (not a template) to one number, but only within 24 hours of that contact's last message to your number (app2email stops 15 minutes early; `window_closes_at` in the answer is the exact time, and `window_open` in `GET /v1/{number}/conversations` says whether it is open now). `text`: `{\"body\": \"...\", \"preview_url\": false}`. `image`, `video`, `document`: `link`, base64 `data` (with `filename`) or a media `id`, plus an optional `caption`. Optional `reply_to` quotes one of the contact's messages (a `wamid.` id). Outside the window: 422 `outside_24h_window`; send an approved template instead. The Do Not Call list does not apply, because the contact wrote to you, except when their last message was the opt-out itself (403 `recipient_opted_out` until they write again). Counts as one message of the plan.\n\n**Scheduled sends:** add `\"send_at\": \"2026-11-02T09:00:00+11:00\"` (ISO 8601 with a time zone, 1 minute to 29 days ahead) to a template send (one number or a list). The answer is HTTP 202 with `status: \"scheduled\"` and the broadcast code. Everything is checked at once; the Do Not Call list and the monthly limit are checked again when the time comes. Cancel with `POST /v1/{number}/broadcasts/{code}/cancel`.\n\n**Several recipients:** put a list of numbers in `to`, separated by commas (`\"61412345678,61498765432\"`), or as a JSON array. Each number gets its own message with the same values; duplicates are sent once. The answer then has one entry per number in `results`, and the HTTP status is 200 when all were accepted, 207 when some were. The most numbers per request is the number's broadcast limit (as on the Broadcast page, up to 1000). A list is recorded as a broadcast in the Activity Log under Broadcasts, with its delivered, read and reply counts; name it with the optional `campaign_name` (default \"API: <template name>\"). `broadcast.report_url` in the answer is its report page.\n\n**Different values for each number:** send `recipients` instead of `to`: `[{\"to\": \"61412345678\", \"components\": [...]}, ...]`. Each entry's components replace the shared `template.components` of the same type (a button: the same `index`), so a shared image header can go with each person's own body values. Every number is checked before anything is sent. Recorded as a broadcast, like a list in `to`.\n\n**Media headers:** image, video or document as `link` (app2email downloads it), base64 `data` in the request, or a WhatsApp media `id`. Leave the header component out to send the template's own sample image, video or document. WhatsApp limits: images (JPG/PNG) 5 MB, videos (MP4/3GP) 16 MB, documents 100 MB. Requests can be up to 140 MB (a 100 MB file as base64).\n\n**Test without sending:** add `\"dry_run\": true`. Everything is checked as for a real send (template values, numbers, Do Not Call list, monthly limit, media links and files downloaded and checked); the answer shows the exact WhatsApp message per number. Nothing is sent, logged or counted.\n\n**Big lists in the background:** add `\"background\": true`. After the checks (and any media upload) the call answers HTTP 202 with `broadcast.status_url`, and the messages are sent after. Follow the progress with `GET /v1/{number}/broadcasts/{code}` or the `broadcast.completed` webhook event.\n\n**Buttons and lists:** `\"type\": \"interactive\"` sends reply buttons (up to 3), a list (up to 10 rows) or a URL button, within the 24 hour window like a text. The contact's tap arrives as a `message.received` event with `button.payload`.\n\n**Contacts without a phone number:** WhatsApp is moving to usernames with business-scoped user ids (BSUIDs, like `61.AbC123`): a `message.received` event or `GET /messages` may carry `from_user_id` and no number. Put the id in `to` (or `recipient`); everything that takes a contact (conversations, contacts, owner) takes a BSUID too. One-tap and copy-code authentication templates still need a phone number.\n\n**Segments:** `\"segment\": \"<id or name>\"` instead of `to` sends a template to the contacts of a saved segment (`/contacts`, `/segments`). A named template parameter without a value is filled from each contact's `custom_fields` (`name` from the contact's name).\n\n**Conversation owner (handoff):** `PUT /v1/{number}/conversations/{contact}/owner` with `human`, `agent`, `paused` or `\"\"` says who handles a contact. With `human` or `paused`, app2email's auto reply and the A2A / OpenClaw agent leave the contact alone; the `conversation.owner_changed` event tells everyone else. `GET /conversations/{contact}` has `window_state`, `window_closes_at` and the owner.\n\n**Sandbox keys:** a key with the sandbox flag (API key page) does every check for real and sends nothing: the answer has `\"sandbox\": true` and ids starting `wamid.SANDBOX.`, and `message.status` events sent, delivered and read follow within seconds, so an automation can be tested end to end.\n\n**Caps and approvals:** a key can have a daily cap (429 `daily_cap_reached`) and an approval gate: a send to more contacts than `approval_above` is held (202 `pending_approval` with `approval.url`) until a person approves it on the dashboard or another key calls `POST /approvals/{id}/approve`; `message.held_for_approval` and `approval.resolved` events report it. The number's own monthly cap is a setting (`caps.monthly_messages`, 429 `monthly_cap_reached`).\n\n**What WhatsApp charges:** `meta_pricing` in `GET /usage` (and `GET /usage/meta` per day) counts the billing month's messages by Meta's pricing category - the 1,000 free service messages per month, billable service, utility, marketing, authentication - with an indicative cost estimate. Meta bills you directly.\n\n**Stored inbound media:** WhatsApp's media ids for received files expire after 7 days, so app2email keeps a copy: `GET /v1/{number}/media/{message_id}` serves it (also `media_url` in `GET /messages`).\n\n**Safe retries:** send an `Idempotency-Key` header (a unique value per message or list, eg a UUID or your order number). The same request with the same key within 24 hours is not sent again: it gets the first answer, with the header `Idempotent-Replayed: true`. Same key, different body: 422 `idempotency_key_reused`. First request still sending: 409 `idempotency_request_in_progress`. First request did not finish within 15 minutes: 409 `idempotency_request_interrupted`; some messages may have gone out, so check before sending with a new key. A request refused before anything was sent leaves the key free. Dry runs ignore the key.\n\n**Status:** `GET /v1/{number}/messages/{message_id}` (any message sent from the number: status, times, error, reply), `GET /v1/{number}/broadcasts` and `GET /v1/{number}/broadcasts/{code}` (counts and the result per number, live while sending), `GET /v1/{number}/broadcasts/{code}/results.csv` (the result per message as CSV), `GET /v1/{number}/usage` (plan, messages used and left this month, the most numbers per request), `GET /v1/{number}/usage/history` (per month), `GET /v1/{number}/stats?from=&to=` (sent, delivered, read, failed and replied counts and rates for a period).\n\n**Reading messages:** `GET /v1/{number}/messages` lists messages sent and received, newest first, filtered by `since`, `until`, `direction` (in/out), `status`, `to`, `broadcast`; `GET /v1/{number}/conversations` lists the contacts, and `GET /v1/{number}/conversations/{phone}/messages` one contact's messages. Times are ISO 8601. Pages: pass the `next_cursor` of the answer as `cursor`.\n\n**Do Not Call list:** `GET /v1/{number}/donotcall` (or `?number=` to check one), `POST` to add, `DELETE /v1/{number}/donotcall/{phone}` to remove. The same list as in the dashboard; marketing templates are not sent to these numbers.\n\n**Webhooks:** `POST /v1/{number}/webhooks` with a public https `url`. Every webhook gets every event; the event's `type` (also in the `X-App2email-Event` header) says which it is, so handle the types you need and answer 2xx to the rest. Every event with its payload: https://www.app2email.com/docs/api/webhooks. Each event is a POST of JSON `{id, type, created, number, data}` (see the WebhookEvent schema) with the headers `X-App2email-Event`, `X-App2email-Delivery`, `X-App2email-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's secret>` (two `v1=` while an old secret is still kept: accept either) and `X-Hub-Signature-256: sha256=<hex HMAC-SHA256 of the raw body with the webhook's secret>` (the way Meta signs WhatsApp webhooks; no time in it, current secret only). Answer 2xx within 10 seconds; otherwise it is sent again after 10 s, 1 min, 5 min, 30 min, 1, 2, 4, 8 and 16 hours (the planned tries survive a restart). Events can arrive out of order. Up to 5 webhooks per number. After many failed deliveries in a row the webhook is switched off (`active: false`) until you turn it on again with `PATCH`. Change a webhook with `PATCH /v1/{number}/webhooks/{id}` (url, active, headers, format), replace its signing secret with `POST .../webhooks/{id}/rotate-secret` (`{\"keep_old_for_hours\": 24}` keeps the old one signing too until `previous_secret_until`), and look at the last 7 days of deliveries with `GET .../webhooks/{id}/deliveries` (`?status=failed`); `POST .../deliveries/{event_id}/redeliver` sends one again. `POST .../webhooks/{id}/test` sends a test event: no body for a `ping`, `{\"type\": \"message.received\"}` for that event's sample, or `{\"event\": {...}}` for your own (sent once, with `\"test\": true` and the header `X-App2email-Test: true`; 30 an hour). `GET .../webhooks/samples` has a sample of every event. `POST .../webhooks/test-url` tests any https URL; `POST .../webhooks/catchers` gives a temporary URL that keeps what it receives. A webhook can have custom `headers` and a `format` (`app2email` or `meta`: WhatsApp's events as Meta's own body). Webhooks can also be added, tested and checked without code on https://www.app2email.com/dashboard/apikey (Webhooks).\n\n**Templates and media:** `GET /v1/{number}/templates/{name}` shows every language of one template with its status and rejection reason. `POST /v1/{number}/templates` creates a template and submits it to WhatsApp for review (201, status PENDING; the `template.status_changed` event tells the result). `DELETE /v1/{number}/templates/{name}` deletes it. `POST /v1/{number}/media` uploads a file once and returns a `media_id` to use in many sends (kept by WhatsApp 30 days).\n\n**Settings and opt-ins:** `GET` and `PUT /v1/{number}/settings/autoreply` (the Default first reply a new contact gets), `GET` and `PUT /v1/{number}/settings/forwarding` (the Default addresses that get the messages by email; Auto Reply cards and Email Rules set on the dashboard by date, day, time or keyword are checked before Default), `GET` and `PUT /v1/{number}/settings/optin` (when on, marketing templates go only to numbers with an opt-in record). Opt-ins are your own proof of consent: `POST /v1/{number}/optins`, `GET /v1/{number}/optins`, `DELETE /v1/{number}/optins/{phone}`.\n\n**Appointment bookings:** customers book appointments inside WhatsApp (a WhatsApp Flow the dashboard's Book-and-Pay section designs and publishes); the business's calendar (Google, Microsoft, iCloud / CalDAV, an ICS link, or app2email's built-in one), or a booking service (Cal.com, Calendly, Acuity Scheduling, Square Appointments, Microsoft Bookings, SimplyBook.me, Setmore, Zoho Bookings) decides what is free. `GET /v1/{number}/bookings` lists the appointments (filter by day, status, contact), `GET /v1/{number}/bookings/availability?service_id=` the free slots per day, `POST /v1/{number}/bookings` books one for a customer (they get the confirmation on WhatsApp), `POST .../bookings/{id}/cancel` cancels, `POST .../bookings/{id}/status` marks it completed or a no-show, `GET .../bookings/reports?days=30` gives the numbers. `GET` and `PUT /v1/{number}/settings/booking` read and change the settings (services, hours, messages, calendar, staff; a partial PUT merges by section). `GET /v1/{number}/flows` marks the number's Book-and-Pay Flows with their `key` and `can_send`, and `POST /v1/{number}/flows/{key}/send` sends one to a contact inside their 24 hour window. Scope `bookings:manage` (the reads also with `messages:read`); the events `booking.created`, `booking.cancelled`, `booking.rescheduled`, `booking.rated` and `flow.completed` report what customers do.\n\n**Event tickets:** a business sells tickets to its events on WhatsApp and on its own event page, takes the money through its own Stripe or PayPal account, and scans the QR tickets at the door. `GET /v1/{number}/tickets/events` lists the events, `GET .../tickets/events/{id}/availability` says what is on sale and how many are left, `GET /v1/{number}/tickets/orders` and `GET /v1/{number}/tickets/issued` list the orders and the tickets with their check-in state. `POST /v1/{number}/tickets/orders` issues complimentary tickets or records a sale paid outside (the buyer gets the tickets on WhatsApp or by email), `POST .../tickets/orders/{id}/refund` refunds, `POST /v1/{number}/tickets/check-ins` checks a ticket in by its code. Events, dates, ticket types and promo codes can be created and changed; seat plans are drawn on the dashboard. `GET` and `PUT /v1/{number}/settings/tickets` read and change the settings. Scope `tickets:manage`; the events `ticket.order.confirmed`, `ticket.order.refunded`, `ticket.checked_in`, `ticket.passed_on`, `ticket.event.sold_out`, `ticket.event.cancelled`, `ticket.waitlist.joined` and `ticket.buyer.erased` report what happens. A number where ticket sales are not switched on answers 403 `tickets_not_enabled`; `GET /v1/{number}/settings/tickets` says whether they are available.\n\n**Account:** `GET /v1/{number}/me` (the key, its scopes and the limits that apply).\n\n**Tip:** `GET /v1/{number}/templates` returns every template with a complete `example_request` you can send as-is after changing the values.\n\n**Errors** are JSON with a stable `error.code`, a `message`, `how_to_fix`, and where useful `details` and a correct `example_request`. Quote `request_id` when contacting support@app2email.com.\n\nSent messages appear in the app2email Activity Log (WhatsApp sent) with delivered/read status, and in the conversation history; a list of numbers also under Broadcasts. They count towards the plan's monthly message limit, which covers outgoing WhatsApp messages and outgoing emails added together (incoming messages do not count). Marketing templates are not sent to numbers on the account's Do Not Call list.",
    "contact": {
      "name": "app2email support",
      "email": "support@app2email.com",
      "url": "https://www.app2email.com"
    }
  },
  "host": "api.app2email.com",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "ApiKeyHeader": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-KEY",
      "description": "Your API key from https://www.app2email.com/dashboard/apikey"
    }
  },
  "security": [
    {
      "ApiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "Messages",
      "description": "Send WhatsApp messages (templates and free-form replies), read them and look up their status."
    },
    {
      "name": "Media",
      "description": "Upload files for sends; download the files contacts sent."
    },
    {
      "name": "Conversations",
      "description": "One thread per contact: the 24 hour window, its messages and its owner (handoff)."
    },
    {
      "name": "Templates",
      "description": "Your WhatsApp templates: list, create, look up, delete."
    },
    {
      "name": "Flows",
      "description": "WhatsApp Flows: forms and screens inside WhatsApp. Shared by every number of the WhatsApp Business Account."
    },
    {
      "name": "Book-and-Pay",
      "description": "Appointment bookings made on WhatsApp Flows: the appointments, the free slots, the booking settings, and sending the number's Flows."
    },
    {
      "name": "Tickets-and-Pay",
      "description": "Coming soon: ticket sales are being switched on number by number. Until a number is switched on, every call in this group answers 403 tickets_not_enabled and GET /settings/tickets says available: false. Event tickets: events with one or many dates, ticket types and extras, what is left, orders and refunds, the tickets with their check-in state, promo codes, the waiting list and door lists. Create a key with the permission Event tickets on the API keys page. Your systems can list events and what is left, find an order, issue complimentary tickets or record a sale paid at your till, refund, send tickets again, and check tickets in from your own scanner. Eight webhook events report an order confirmed or refunded, a ticket checked in or passed on, a date sold out or cancelled, a waiting-list entry and an erased buyer. AI assistants can do the same through the hosted MCP server. Sandbox keys can read but cannot issue, refund or check in."
    },
    {
      "name": "Submit-Info",
      "description": "Forms a business defines as a plain list of questions. app2email turns each one into a WhatsApp form and a web page; what people send becomes a submission that moves through stages in a shared inbox and sets off automations: replies, e-mails, calculations and calls to outside systems. Start with GET /submit/guide, build everything with one POST /submit/setup, then publish the form."
    },
    {
      "name": "Order-and-Pay",
      "description": "A product catalog with its own order page: customers order from WhatsApp or the web for pickup or delivery, pay online or at the counter, and collect with a QR code. Orders are managed in the dashboard and the counter app; these events tell your system what happens to an order."
    },
    {
      "name": "Broadcasts",
      "description": "Lists of numbers (API or Broadcast page): status, the result per number, scheduling and cancelling."
    },
    {
      "name": "Contacts",
      "description": "Contacts with tags, custom fields and consent records, and segments (saved filters) to send to."
    },
    {
      "name": "Opt-ins",
      "description": "Records that people agreed to your messages, and the rule that requires them for marketing."
    },
    {
      "name": "Do Not Call",
      "description": "Numbers marketing templates are not sent to."
    },
    {
      "name": "Approvals",
      "description": "Sends held by a key's approval gate, waiting for a person."
    },
    {
      "name": "Number",
      "description": "The number at WhatsApp: health, business profile, display name, username, QR codes, conversation starters, commerce."
    },
    {
      "name": "Settings",
      "description": "Auto reply, email forwarding, and the number's settings (email behaviour, caps, compliance)."
    },
    {
      "name": "Webhooks",
      "description": "Events sent to your URL: https://www.app2email.com/docs/api/webhooks"
    },
    {
      "name": "Analytics",
      "description": "WhatsApp's own figures: cost and volume, sent and delivered, the account's activity log, conversion events."
    },
    {
      "name": "Calling",
      "description": "WhatsApp voice calls through your own WebRTC or SIP stack: settings, call actions, call permissions."
    },
    {
      "name": "Account",
      "description": "The key, plan, usage, statistics and the request log."
    },
    {
      "name": "Calendar",
      "description": "The business calendar: appointments, blocked time, internal notes, links to the online booking page and held times. Services, staff and the next free times for agents."
    },
    {
      "name": "Payments",
      "description": "Payments for appointments through the business's own Stripe or PayPal account, one-off payment requests, refunds, prepaid packages, the customer profile (with GDPR-style erase) and meeting polls."
    }
  ],
  "paths": {
    "/v1/{number}/messages": {
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "listMessages",
        "summary": "Messages sent and received, newest first",
        "description": "Messages sent from the number (`direction` out, with their status and times) and received from contacts (`direction` in). Filters: a time window, the direction, the status of sent messages, one contact, or one broadcast. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only messages at or after this time. ISO 8601, eg 2026-10-25T10:00:00Z.",
            "type": "string",
            "x-example": "2026-10-25T10:00:00Z"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "Only messages before this time. ISO 8601.",
            "type": "string",
            "x-example": "2026-10-26T00:00:00Z"
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "in: received. out: sent. Left out: both.",
            "type": "string",
            "enum": [
              "in",
              "out"
            ]
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Sent messages only: queued, accepted, sent, delivered, read or failed. Not with direction=in.",
            "type": "string",
            "enum": [
              "queued",
              "accepted",
              "sent",
              "delivered",
              "read",
              "failed"
            ]
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Only with this contact (full number, digits, with country code).",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "broadcast",
            "in": "query",
            "required": false,
            "description": "Only the messages of this broadcast (its code).",
            "type": "string",
            "x-example": "k3XbQ9rTzP2mWv7a1c9e"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The messages.",
            "schema": {
              "$ref": "#/definitions/MessagesListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h5vnq",
                "messages": [
                  {
                    "direction": "in",
                    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                    "from": "61412345678",
                    "name": "John",
                    "text": "Yes, Friday works",
                    "media": null,
                    "time": "2026-10-26T01:20:44Z",
                    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
                  },
                  {
                    "direction": "out",
                    "message_id": "wamid.HBgLNjE0OTg3NjU0MzIVAgARGBJTQU1QTEVfT1VUQk9VTkQwMgA=",
                    "to": "61498765432",
                    "status": "read",
                    "sent_by": "api",
                    "text": "Hi Mary, your order #1235 has shipped.",
                    "time": "2026-10-26T01:12:09Z",
                    "times": {
                      "submitted": "2026-10-26T01:12:08Z",
                      "accepted": "2026-10-26T01:12:09Z",
                      "sent": "2026-10-26T01:12:10Z",
                      "delivered": "2026-10-26T01:12:11Z",
                      "read": "2026-10-26T01:15:02Z"
                    }
                  }
                ],
                "next_cursor": "MjAyNi0xMC0yNlQwMToxMjowOVp8NDI",
                "count": 2
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Messages"
        ],
        "operationId": "sendTemplateMessage",
        "summary": "Send a WhatsApp message: template, or free-form reply",
        "description": "Sends one approved template to one recipient, or to several when `to` lists several numbers (or `recipients` gives each number its own values). The parameters are checked against the template before sending; on a mismatch the error includes a complete, correct `example_request` for that template. Nothing is sent when the request itself is invalid. `dry_run` checks without sending; `background` answers 202 and sends after; `send_at` schedules it (202, status scheduled). `type` text, image, video, document or interactive sends a free-form message to one contact within 24 hours of the contact's last message (422 outside_24h_window otherwise). `segment` sends a template to a saved segment's contacts. A business-scoped user id works wherever a number does. Also `audio`, `sticker`, `location`, `contacts`, `reaction` and the newer interactive kinds; template carousels, limited-time offers, catalog, MPM, SPM, flow and OTP buttons. `callback_data` comes back in message.status. MARKETING templates follow `marketing_api` / messages.marketing_route (`sent_via` in the answer).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SendTemplateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted by WhatsApp (all numbers, when several were given). A dry run also answers 200. A free-form message answers 200 too. A sandbox key answers 200 with sandbox: true.",
            "schema": {
              "$ref": "#/definitions/SendMessageResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "kxrkf",
                "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                "status": "accepted",
                "from": "4976659348270",
                "to": "61412345678",
                "template": {
                  "name": "order_update",
                  "language": "en",
                  "category": "UTILITY"
                },
                "text": "Hi John, your order #1234 has shipped.",
                "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_...",
                "note": "accepted by WhatsApp. delivery and read status appear in your app2email Activity Log (WhatsApp sent).",
                "contacts": [
                  {
                    "input": "61412345678",
                    "wa_id": "61412345678"
                  }
                ]
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "type": "string",
                "description": "true when this is the stored answer of an earlier request with the same Idempotency-Key."
              }
            }
          },
          "202": {
            "description": "\"background\": true - checked, and sending has started (progress: broadcast.status_url). Or \"send_at\" - status scheduled, sent at scheduled_for (cancel with POST /broadcasts/{code}/cancel). Or status pending_approval: held by the key's approval gate until a person approves it (approval.url). The example is the background answer.",
            "schema": {
              "$ref": "#/definitions/SendMessageResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t7wpe",
                "status": "queued",
                "from": "4976659348270",
                "template": {
                  "name": "october_newsletter",
                  "language": "en",
                  "category": "MARKETING"
                },
                "broadcast": {
                  "name": "October newsletter",
                  "code": "k3XbQ9rTzP2mWv7a1c9e",
                  "report_url": "https://www.app2email.com/dashboard/log/broadcast/k3XbQ9rTzP2mWv7a1c9e",
                  "status_url": "https://api.app2email.com/v1/4976659348270/broadcasts/k3XbQ9rTzP2mWv7a1c9e"
                },
                "recipients": 3,
                "queued": 3,
                "skipped": 0,
                "results": [],
                "note": "Sending in the background. GET broadcast.status_url for progress and the result for each number, or use the broadcast.completed webhook."
              }
            }
          },
          "207": {
            "description": "Several numbers: some were accepted, some not. 'results' has the outcome per number.",
            "schema": {
              "$ref": "#/definitions/SendMessageResponse"
            },
            "examples": {
              "application/json": {
                "success": false,
                "request_id": "q8m2d",
                "status": "partially_accepted",
                "from": "4976659348270",
                "template": {
                  "name": "order_update",
                  "language": "en",
                  "category": "UTILITY"
                },
                "text": "Hi John, your order #1234 has shipped.",
                "broadcast": {
                  "name": "Order updates 21 Oct",
                  "code": "k3XbQ9rTzP2mWv7a1c9e",
                  "report_url": "https://www.app2email.com/dashboard/log/broadcast/k3XbQ9rTzP2mWv7a1c9e"
                },
                "recipients": 3,
                "accepted": 2,
                "failed": 1,
                "results": [
                  {
                    "to": "61412345678",
                    "success": true,
                    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                    "status": "accepted",
                    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
                  },
                  {
                    "to": "61498765432",
                    "success": true,
                    "message_id": "wamid.HBgLNjE0OTg3NjU0MzIVAgARGBJTQU1QTEVfT1VUQk9VTkQwMgA=",
                    "status": "accepted",
                    "conversation_url": "https://www.app2email.com/conversation/61498765432_4976659348270_..."
                  },
                  {
                    "to": "61400111222",
                    "success": false,
                    "error": {
                      "code": "recipient_unreachable",
                      "message": "WhatsApp did not send the message: ...",
                      "how_to_fix": "WhatsApp could not deliver to this number. Check it is a WhatsApp number written with its country code ..."
                    }
                  }
                ],
                "note": "accepted by WhatsApp. delivery and read status appear in your app2email Activity Log under Broadcasts (broadcast.report_url)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/messages/{message_id}": {
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "getMessageStatus",
        "summary": "Status of a sent message",
        "description": "Any message sent from the number (API, Broadcast page, email replies): status, the time of each step, why it failed, and the contact's reply or button tap.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "description": "The message_id from the send answer (starts with 'wamid.'). URL-encode it.",
            "type": "string",
            "x-example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA="
          }
        ],
        "responses": {
          "200": {
            "description": "The message.",
            "schema": {
              "$ref": "#/definitions/MessageStatusResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "listTemplates",
        "summary": "List your templates, with an example request for each",
        "description": "All templates of the number's WhatsApp account: status, category, what values each needs, and for approved templates a complete example request.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The templates.",
            "schema": {
              "$ref": "#/definitions/TemplatesResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "createTemplate",
        "summary": "Create a template and submit it for approval",
        "description": "Needs the 'templates:manage' scope. The template goes to WhatsApp for review (minutes to a day). `template.status_changed` tells the result. Every Meta field is passed on (TTL, link tracking, max price, Template Library). WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TemplateCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Submitted (status PENDING).",
            "schema": {
              "$ref": "#/definitions/TemplateCreateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c3ppl",
                "template": {
                  "id": "2234567890",
                  "name": "order_update",
                  "language": "en",
                  "category": "UTILITY",
                  "status": "PENDING"
                },
                "note": "Submitted to WhatsApp for review (minutes to a day). You get a template.status_changed webhook event with the result, or GET https://api.app2email.com/v1/4976659348270/templates/order_update."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates/{name}": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "getTemplate",
        "summary": "One template: status, rejection reason, what it needs",
        "description": "Every language of the template. Not from a cache: a status that just changed shows. With every field Meta keeps (sub_category, previous_category, TTL, link tracking, library name).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The template's name.",
            "type": "string",
            "x-example": "order_update"
          }
        ],
        "responses": {
          "200": {
            "description": "The template's languages.",
            "schema": {
              "$ref": "#/definitions/TemplateDetailResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "k7qtm",
                "name": "order_update",
                "versions": [
                  {
                    "id": "1234567890",
                    "name": "order_update",
                    "language": "en",
                    "category": "UTILITY",
                    "status": "APPROVED",
                    "can_send": true,
                    "needs": {
                      "body": "2 text values"
                    },
                    "example_request": {
                      "to": "61412345678",
                      "type": "template",
                      "template": {
                        "name": "order_update",
                        "language": {
                          "code": "en"
                        },
                        "components": [
                          {
                            "type": "body",
                            "parameters": [
                              {
                                "type": "text",
                                "text": "John"
                              },
                              {
                                "type": "text",
                                "text": "#1234"
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Templates"
        ],
        "operationId": "deleteTemplate",
        "summary": "Delete a template (every language, or one)",
        "description": "Needs the 'templates:manage' scope. The template app2email uses for its own alerts cannot be deleted here. WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The template's name.",
            "type": "string",
            "x-example": "order_update"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Only this language. Default: every language.",
            "type": "string",
            "x-example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/TemplateDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "e2mxa",
                "deleted": "order_update",
                "languages": [
                  "en"
                ],
                "note": "All languages of the template were deleted. The same name and language can be used again after WhatsApp has removed it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Templates"
        ],
        "operationId": "editTemplate",
        "summary": "Edit a template (components, category, TTL, max price)",
        "description": "Needs 'templates:manage'. Only APPROVED, REJECTED or PAUSED templates; an approved one at most once a day, 10 times in 30 days. WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The template's name.",
            "type": "string",
            "x-example": "order_update"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "The template's language (eg en, en_US). Needed when the template has several.",
            "type": "string",
            "x-example": "en"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TemplateEditRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed (components: WhatsApp reviews them again).",
            "schema": {
              "$ref": "#/definitions/TemplateEditResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t2edt",
                "template": {
                  "id": "1234567890",
                  "name": "order_update",
                  "language": "en",
                  "previous_status": "APPROVED"
                },
                "changed": [
                  "components"
                ],
                "note": "WhatsApp reviews the edited template again; the template.status_changed event tells the result. Every number on this WhatsApp Business Account uses the new version."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/media": {
      "post": {
        "tags": [
          "Media"
        ],
        "operationId": "uploadMedia",
        "summary": "Upload a file once, get a media id",
        "description": "Uploads an image, video, document, audio file or sticker to WhatsApp and returns a `media_id` for `{\"id\": ...}` in later sends (templates or free-form). WhatsApp keeps it 30 days. JSON (a link or base64 data) or multipart/form-data (`file`, optional `type`). Limits: image JPEG/PNG 5 MB, video MP4/3GP 16 MB, audio 16 MB, sticker WebP 100 KB static / 500 KB animated, document 100 MB. A sandbox key checks the file and uploads nothing.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MediaUploadRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Uploaded.",
            "schema": {
              "$ref": "#/definitions/MediaUploadResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "g4vbq",
                "media_id": "1234567890",
                "type": "image",
                "filename": "photo.jpg",
                "info": {
                  "mime_type": "image/jpeg",
                  "size_bytes": 248113
                },
                "expires_in_days": 30,
                "note": "Use it as {\"image\": {\"id\": \"1234567890\"}} in a template header or a free-form message. WhatsApp keeps uploaded files for 30 days."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/broadcasts": {
      "get": {
        "tags": [
          "Broadcasts"
        ],
        "operationId": "listBroadcasts",
        "summary": "Your latest broadcasts",
        "description": "Broadcasts sent through the API (several numbers) and from the Broadcast page, newest first.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100, default 20).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20
          }
        ],
        "responses": {
          "200": {
            "description": "The broadcasts.",
            "schema": {
              "$ref": "#/definitions/BroadcastsResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/broadcasts/{code}": {
      "get": {
        "tags": [
          "Broadcasts"
        ],
        "operationId": "getBroadcast",
        "summary": "A broadcast's status and the result per number",
        "description": "Counts and the result for each number, live while a background send runs.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "broadcast.code from the send answer, or from GET /broadcasts.",
            "type": "string",
            "x-example": "k3XbQ9rTzP2mWv7a1c9e"
          }
        ],
        "responses": {
          "200": {
            "description": "The broadcast.",
            "schema": {
              "$ref": "#/definitions/BroadcastStatusResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/broadcasts/{code}/results.csv": {
      "get": {
        "tags": [
          "Broadcasts"
        ],
        "operationId": "getBroadcastCsv",
        "summary": "A broadcast's result for each message, as CSV",
        "description": "One row per message: number, status, message_id, the time of each step, the reply and the error. Opens in a spreadsheet. Values that start with = + - or @ get a ' in front, so a spreadsheet does not run them as formulas.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "broadcast.code from the send answer, or from GET /broadcasts.",
            "type": "string",
            "x-example": "k3XbQ9rTzP2mWv7a1c9e"
          }
        ],
        "responses": {
          "200": {
            "description": "The CSV file (Content-Disposition: attachment).",
            "schema": {
              "type": "string"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "produces": [
          "text/csv",
          "application/json"
        ]
      }
    },
    "/v1/{number}/broadcasts/{code}/cancel": {
      "post": {
        "tags": [
          "Broadcasts"
        ],
        "operationId": "cancelBroadcast",
        "summary": "Cancel a scheduled or sending API broadcast",
        "description": "Needs the 'messages:send' scope. A scheduled broadcast (send_at) is removed: nothing is sent (200). A broadcast that is sending now (API list, background or scheduled): the messages not yet handed to WhatsApp are not sent, those already sent stay sent (202, status cancelling). Broadcasts started from the dashboard, and finished ones, cannot be cancelled here (409 broadcast_not_cancellable). broadcast.completed is sent with data.status cancelled.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "broadcast.code from the send answer.",
            "type": "string",
            "x-example": "k3XbQ9rTzP2mWv7a1c9e"
          }
        ],
        "responses": {
          "200": {
            "description": "Scheduled broadcast removed.",
            "schema": {
              "$ref": "#/definitions/BroadcastCancelResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u1nqc",
                "broadcast": {
                  "code": "k3XbQ9rTzP2mWv7a1c9e",
                  "status": "cancelled"
                },
                "sent_before_cancel": 0,
                "note": "It was scheduled and had not started: nothing was sent."
              }
            }
          },
          "202": {
            "description": "Cancelling: the sending stops.",
            "schema": {
              "$ref": "#/definitions/BroadcastCancelResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u1nqd",
                "broadcast": {
                  "code": "k3XbQ9rTzP2mWv7a1c9e",
                  "status": "cancelling"
                },
                "note": "Cancelling. Messages already handed to WhatsApp stay sent; the rest are not sent. GET https://api.app2email.com/v1/4976659348270/broadcasts/k3XbQ9rTzP2mWv7a1c9e shows the result."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getMe",
        "summary": "Check the key: its scopes, the number, the plan and the limits",
        "description": "Works with any valid key, whatever its scopes. Use it for a 'test connection' step in Zapier, Make, n8n or Power Automate.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The key and the number.",
            "schema": {
              "$ref": "#/definitions/MeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a7k3p",
                "key_valid": true,
                "api_version": "v1",
                "number": "4976659348270",
                "plan": "standard_5000",
                "service_status": "LIVE",
                "key": {
                  "name": "Zapier",
                  "scopes": [
                    "messages:read",
                    "messages:send"
                  ],
                  "ip_allow": ""
                },
                "limits": {
                  "max_numbers_per_request": 1000,
                  "requests_per_second": 20,
                  "burst": 50,
                  "rate_limit_mode": "log_only",
                  "webhooks_max": 5
                },
                "scopes_available": [
                  "messages:send",
                  "messages:read",
                  "dnc:manage",
                  "webhooks:manage",
                  "templates:manage",
                  "settings:manage",
                  "contacts:manage",
                  "calls:manage",
                  "bookings:manage",
                  "submissions:manage",
                  "orders:manage",
                  "tickets:manage"
                ]
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/requests": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "listRequests",
        "summary": "The latest logged API requests",
        "description": "Only errors (status 400 and up) and requests that change something (sends, webhook and settings changes) are logged, for 30 days. Each one has its request_id, route, status, time, key and address. No bodies and no keys are stored.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "error (400 and up), ok (below 400), or an HTTP status such as 422.",
            "type": "string",
            "x-example": "error"
          }
        ],
        "responses": {
          "200": {
            "description": "The requests, newest first.",
            "schema": {
              "$ref": "#/definitions/RequestsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "x9d2m",
                "requests": [
                  {
                    "request_id": "kxrkf",
                    "time": "2026-10-26T01:12:09Z",
                    "method": "POST",
                    "route": "/v1/4976659348270/messages",
                    "status": 422,
                    "ms": 412,
                    "key": "Zapier",
                    "ip": "203.0.113.7"
                  }
                ],
                "note": "Only errors and requests that change something are logged. Rows are kept 30 days."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/requests/{id}": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getRequest",
        "summary": "One logged request, by its request_id",
        "description": "The request_id of any answer, for example from a failed send.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The request_id from an answer.",
            "type": "string",
            "x-example": "kxrkf"
          }
        ],
        "responses": {
          "200": {
            "description": "The request.",
            "schema": {
              "$ref": "#/definitions/RequestResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p3uvn",
                "request": {
                  "request_id": "kxrkf",
                  "time": "2026-10-26T01:12:09Z",
                  "method": "POST",
                  "route": "/v1/4976659348270/messages",
                  "status": 422,
                  "ms": 412,
                  "key": "Zapier",
                  "ip": "203.0.113.7"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversations": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "operationId": "listConversations",
        "summary": "The contacts, most recent activity first",
        "description": "One entry per contact, with the last message in each direction and whether a free-form reply can be sent now (window_open).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only contacts active at or after this time. ISO 8601.",
            "type": "string"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The contacts.",
            "schema": {
              "$ref": "#/definitions/ConversationsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q2lzd",
                "conversations": [
                  {
                    "contact": "61412345678",
                    "name": "John",
                    "last_inbound": "2026-10-26T01:20:44Z",
                    "last_outbound": "2026-10-26T01:12:09Z",
                    "window_open": true,
                    "messages": 12,
                    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversations/{phone}/messages": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "operationId": "listConversationMessages",
        "summary": "One contact's messages, both directions",
        "description": "The messages with one contact, newest first. window_open says whether a free-form reply can be sent now.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "description": "The contact's number, with country code, or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "At or after this time. ISO 8601.",
            "type": "string"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "Before this time. ISO 8601.",
            "type": "string"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The messages.",
            "schema": {
              "$ref": "#/definitions/ConversationMessagesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d8ce1",
                "contact": "61412345678",
                "window_open": true,
                "messages": [
                  {
                    "direction": "in",
                    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                    "from": "61412345678",
                    "name": "John",
                    "text": "Yes, Friday works",
                    "media": null,
                    "time": "2026-10-26T01:20:44Z",
                    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/usage/history": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsageHistory",
        "summary": "Messages and broadcasts per month",
        "description": "Per calendar month (UTC), newest first: messages sent, failed, received and broadcasts.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "months",
            "in": "query",
            "required": false,
            "description": "How many months (1 to 24, default 6).",
            "type": "integer",
            "minimum": 1,
            "maximum": 24,
            "default": 6
          }
        ],
        "responses": {
          "200": {
            "description": "The months.",
            "schema": {
              "$ref": "#/definitions/UsageHistoryResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m4ry7",
                "number": "4976659348270",
                "months": [
                  {
                    "month": "2026-10",
                    "messages_sent": 412,
                    "messages_failed": 3,
                    "messages_received": 97,
                    "broadcasts": 2
                  },
                  {
                    "month": "2026-09",
                    "messages_sent": 380,
                    "messages_failed": 1,
                    "messages_received": 88,
                    "broadcasts": 1
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/stats": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getStats",
        "summary": "Message counts, delivery and read rates for a period",
        "description": "For a time range (default the last 30 days, at most 366 days). The same counts as a broadcast report.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start of the range. ISO 8601.",
            "type": "string",
            "x-example": "2026-09-26T00:00:00Z"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End of the range. ISO 8601.",
            "type": "string",
            "x-example": "2026-10-26T00:00:00Z"
          }
        ],
        "responses": {
          "200": {
            "description": "The counts.",
            "schema": {
              "$ref": "#/definitions/StatsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t6bwe",
                "from": "2026-09-26T00:00:00Z",
                "to": "2026-10-26T00:00:00Z",
                "messages": {
                  "submitted": 120,
                  "accepted": 118,
                  "sent": 117,
                  "delivered": 110,
                  "read": 84,
                  "failed": 2,
                  "replied": 19
                },
                "received": 40,
                "rates": {
                  "delivery": 0.9402,
                  "read": 0.7636,
                  "reply": 0.1624
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsage",
        "summary": "Plan, messages used and left, limits, what WhatsApp charges",
        "description": "WhatsApp messages used and left this billing month, the billing period, the most numbers per send request, your own monthly cap, and `meta_pricing`: the month's messages by Meta's pricing category with an indicative cost.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "Usage.",
            "schema": {
              "$ref": "#/definitions/UsageResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/donotcall": {
      "get": {
        "tags": [
          "Do Not Call"
        ],
        "operationId": "listDoNotCall",
        "summary": "The Do Not Call list, or check one number",
        "description": "The whole list, or with ?number= whether that number is on it.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Check only this number (with country code).",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "The list.",
            "schema": {
              "$ref": "#/definitions/DoNotCallListResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Do Not Call"
        ],
        "operationId": "addDoNotCall",
        "summary": "Add numbers to the Do Not Call list",
        "description": "Up to 1000 numbers, with an optional name and note each. Numbers already on the list are left as they are. All or nothing: one invalid number, nothing is added.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/DoNotCallAddRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Added.",
            "schema": {
              "$ref": "#/definitions/DoNotCallAddResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/donotcall/{phone}": {
      "delete": {
        "tags": [
          "Do Not Call"
        ],
        "operationId": "removeDoNotCall",
        "summary": "Remove a number from the Do Not Call list",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "description": "The number to remove, with country code.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "Done ('removed' false: it was not on the list).",
            "schema": {
              "$ref": "#/definitions/DoNotCallRemoveResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/autoreply": {
      "get": {
        "tags": [
          "Settings"
        ],
        "operationId": "getAutoreply",
        "summary": "The auto reply to new contacts",
        "description": "Needs the 'settings:manage' scope. The text of the first reply a new contact gets (the dashboard's Auto reply page).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The text.",
            "schema": {
              "$ref": "#/definitions/AutoreplyResponse"
            },
            "examples": {
              "application/json": {
                "text": "Thanks for writing! We reply within a day."
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Settings"
        ],
        "operationId": "setAutoreply",
        "summary": "Change the auto reply text",
        "description": "Text only: the image and attachment of the auto reply are set on the dashboard. 1 to 4000 characters.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/AutoreplySettings"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/AutoreplyResponse"
            },
            "examples": {
              "application/json": {
                "text": "Thanks for writing! We reply within a day."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/forwarding": {
      "get": {
        "tags": [
          "Settings"
        ],
        "operationId": "getForwarding",
        "summary": "Who gets the messages by email",
        "description": "Needs the 'settings:manage' scope. The email addresses that get each WhatsApp message (the dashboard's Forward email page).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The forwarding settings.",
            "schema": {
              "$ref": "#/definitions/ForwardingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f9hsi",
                "forwarding": {
                  "to": [
                    "a@x.com"
                  ],
                  "cc": [],
                  "bcc": [],
                  "text": "New WhatsApp message",
                  "works_on_this_plan": true,
                  "plan": "standard_5000"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Settings"
        ],
        "operationId": "setForwarding",
        "summary": "Change who gets the messages by email",
        "description": "Fields left out stay as they are. Up to 3 valid emails each for to, cc and bcc. WhatsApp-to-email forwarding works on the Professional and Trial plans (works_on_this_plan says whether it does for this number).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ForwardingSettings"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/ForwardingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f9hsi",
                "forwarding": {
                  "to": [
                    "a@x.com"
                  ],
                  "cc": [],
                  "bcc": [],
                  "text": "New WhatsApp message",
                  "works_on_this_plan": true,
                  "plan": "standard_5000"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/optin": {
      "get": {
        "tags": [
          "Opt-ins"
        ],
        "operationId": "getOptinSetting",
        "summary": "Is the opt-in rule for marketing on?",
        "description": "Needs the 'settings:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The setting.",
            "schema": {
              "$ref": "#/definitions/OptinSettingResponse"
            },
            "examples": {
              "application/json": {
                "require_optin_for_marketing": true
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Opt-ins"
        ],
        "operationId": "setOptinSetting",
        "summary": "Turn the opt-in rule for marketing on or off",
        "description": "When on, MARKETING template messages are only sent to numbers with an opt-in record. Others are skipped (recipient_not_opted_in; a single recipient gets 403). Utility templates and replies are not affected. Off by default.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/OptinSettingRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/OptinSettingResponse"
            },
            "examples": {
              "application/json": {
                "require_optin_for_marketing": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/optins": {
      "get": {
        "tags": [
          "Opt-ins"
        ],
        "operationId": "listOptins",
        "summary": "The opt-in records, or check one number",
        "description": "Your own proof that people agreed to your messages (kept by app2email; nothing else uses it unless the opt-in rule is on). Needs the 'settings:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Check only this number: opted_in true or false.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 100).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 100
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "The next_after of the previous page.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "The opt-ins.",
            "schema": {
              "$ref": "#/definitions/OptinsListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "o1lkr",
                "total": 2,
                "optins": [
                  {
                    "number": "61412345678",
                    "name": "John",
                    "source": "api",
                    "note": "",
                    "at": "2026-10-26T01:00:00Z",
                    "added_by": "api"
                  },
                  {
                    "number": "61498765432",
                    "name": "Mary",
                    "source": "web form",
                    "note": "ticked the box",
                    "at": "2026-10-01T00:00:00Z",
                    "added_by": "api"
                  }
                ],
                "next_after": null,
                "opted_in": null
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Opt-ins"
        ],
        "operationId": "addOptins",
        "summary": "Record that people opted in",
        "description": "Up to 1000 entries, all or nothing. A number already recorded is updated. Needs the 'settings:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/OptinsAddRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/OptinsAddResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "o9ahv",
                "saved": 2
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/optins/{phone}": {
      "delete": {
        "tags": [
          "Opt-ins"
        ],
        "operationId": "removeOptin",
        "summary": "Remove an opt-in record",
        "description": "Needs the 'settings:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "description": "The number, with country code.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "schema": {
              "$ref": "#/definitions/OptinRemoveResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "r6dyw",
                "removed": "61412345678"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversations/{contact}": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "operationId": "getConversation",
        "summary": "One contact: window state, last messages, owner",
        "description": "The conversation with one contact: `window_state` open or closed and `window_closes_at`, the last message each way, held email replies, and who owns it (see PUT .../owner).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "description": "The contact's number (country code first), or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "The conversation.",
            "schema": {
              "$ref": "#/definitions/ConversationDetailResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c9slm",
                "contact": "61412345678",
                "identity_type": "phone",
                "phone": "61412345678",
                "name": "John",
                "window_state": "open",
                "window_open": true,
                "window_closes_at": "2026-10-27T01:05:44Z",
                "last_inbound_at": "2026-10-26T01:20:44Z",
                "last_outbound_at": "2026-10-26T01:12:09Z",
                "messages": 12,
                "owner": "human",
                "owner_set_at": "2026-10-26T01:21:00Z",
                "owner_set_by": "api:Support bot",
                "owner_reason": "customer asked for a person",
                "owner_summary": "Wants to move the delivery to Monday.",
                "held_replies": false,
                "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversations/{contact}/owner": {
      "put": {
        "tags": [
          "Conversations"
        ],
        "operationId": "setConversationOwner",
        "summary": "Hand a contact over: human, agent, paused, or back to normal",
        "description": "Needs the 'messages:send' scope. `human` or `paused`: app2email's auto reply and the A2A / OpenClaw agent leave the contact alone (while the number's setting a2a.respect_owner is on); email forwarding carries on. `agent`: an automation owns it (a marker for everyone else). `\"\"`: the normal routing. `until_minutes` makes it temporary. Fires the conversation.owner_changed webhook event. A number that has never been in touch gets a conversation record so the owner can be set first.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "description": "The contact's number (country code first), or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/OwnerRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/OwnerResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/number": {
      "get": {
        "tags": [
          "Settings"
        ],
        "operationId": "getNumberSettings",
        "summary": "The number's settings: email behaviour, caps, compliance",
        "description": "Every setting with its value (defaults filled in).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The settings.",
            "schema": {
              "$ref": "#/definitions/NumberSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s1xpa",
                "settings": {
                  "email": {
                    "delivery_receipts": "failed_only",
                    "mark_read_on_open": false,
                    "include_history": 20,
                    "history_images": "link"
                  },
                  "caps": {
                    "monthly_messages": 0
                  },
                  "compliance": {
                    "adm_disclosure": "",
                    "stop_keywords_extra": []
                  },
                  "a2a": {
                    "respect_owner": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Settings"
        ],
        "operationId": "updateNumberSettings",
        "summary": "Change some of the number's settings",
        "description": "Needs the 'settings:manage' scope. Only the keys given change; nested objects (`{\"email\": {\"mark_read_on_open\": true}}`) or dotted keys (`{\"email.mark_read_on_open\": true}`) both work. Not with a sandbox key.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/NumberSettings"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The settings as they are now.",
            "schema": {
              "$ref": "#/definitions/NumberSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s1xpa",
                "settings": {
                  "email": {
                    "delivery_receipts": "failed_only",
                    "mark_read_on_open": false,
                    "include_history": 20,
                    "history_images": "link"
                  },
                  "caps": {
                    "monthly_messages": 0
                  },
                  "compliance": {
                    "adm_disclosure": "",
                    "stop_keywords_extra": []
                  },
                  "a2a": {
                    "respect_owner": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "listContacts",
        "summary": "Your contacts, newest first",
        "description": "Filter by a search text, a tag, or consent. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Part of the name or number.",
            "type": "string",
            "x-example": "john"
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only contacts with this tag.",
            "type": "string",
            "x-example": "vip"
          },
          {
            "name": "consent",
            "in": "query",
            "required": false,
            "description": "true: with marketing consent. false: without.",
            "type": "boolean"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The contacts.",
            "schema": {
              "$ref": "#/definitions/ContactsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "l4vne",
                "contacts": [
                  {
                    "identity": "61412345678",
                    "identity_type": "phone",
                    "phone": "61412345678",
                    "name": "John Smith",
                    "tags": [
                      "vip"
                    ],
                    "custom_fields": {
                      "first_name": "John",
                      "order_id": "1234"
                    },
                    "source": "crm",
                    "consent": {
                      "marketing": true,
                      "at": "2026-10-01T09:00:00Z",
                      "source": "web form",
                      "text": "Yes, send me offers on WhatsApp",
                      "evidence": "https://example.com/forms/123",
                      "recorded": true
                    },
                    "last_inbound_at": "2026-10-26T01:20:44Z",
                    "created": "2026-10-01T09:00:10Z",
                    "updated": "2026-10-26T01:20:44Z"
                  }
                ],
                "next_cursor": null,
                "count": 1,
                "total": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "operationId": "upsertContacts",
        "summary": "Make or update contacts (one, or a list of up to 1000)",
        "description": "Needs the 'contacts:manage' scope. Upsert by identity (phone or business-scoped user id): the fields given replace, the ones left out stay. Custom fields merge. `consent` records consent with its evidence. Fires contact.updated for requests of up to 50 contacts.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ContactsUpsertRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/ContactsUpsertResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u8wqb",
                "saved": 1,
                "created": 1,
                "updated": 0,
                "contacts": [
                  {
                    "identity": "61412345678",
                    "identity_type": "phone",
                    "phone": "61412345678",
                    "name": "John Smith",
                    "tags": [
                      "vip"
                    ],
                    "custom_fields": {
                      "first_name": "John",
                      "order_id": "1234"
                    },
                    "source": "crm",
                    "consent": {
                      "marketing": true,
                      "at": "2026-10-01T09:00:00Z",
                      "source": "web form",
                      "text": "Yes, send me offers on WhatsApp",
                      "evidence": "https://example.com/forms/123",
                      "recorded": true
                    },
                    "last_inbound_at": "2026-10-26T01:20:44Z",
                    "created": "2026-10-01T09:00:10Z",
                    "updated": "2026-10-26T01:20:44Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/contacts/import": {
      "post": {
        "tags": [
          "Contacts"
        ],
        "operationId": "importContacts",
        "summary": "Import contacts from CSV or JSON (up to 5000 rows)",
        "description": "Needs the 'contacts:manage' scope. `text/csv` with a header row: phone (or identity / number / mobile), name (or first_name + last_name), tags (separated by |), consent_marketing (yes/no), consent_source, consent_text, consent_evidence, consent_at, source; every other column becomes a custom field. Or `application/json` with a list of contacts as for POST /contacts. Rows with a problem are skipped and listed; the rest are saved.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ContactInput"
              }
            }
          }
        ],
        "consumes": [
          "text/csv",
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Imported.",
            "schema": {
              "$ref": "#/definitions/ContactsImportResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "i2gka",
                "rows": 120,
                "saved": 118,
                "created": 90,
                "updated": 28,
                "skipped": 2,
                "errors": [
                  {
                    "row": 7,
                    "problem": "'0412' must be a WhatsApp number with country code, digits only (8 to 15 digits), or a business-scoped user id like 61.AbC123"
                  }
                ],
                "note": "Rows with a problem were skipped (the first 50 are listed); the rest were saved."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/contacts/export.csv": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "exportContacts",
        "summary": "All contacts as CSV",
        "description": "One row per contact with tags (separated by |), consent and custom fields (as JSON). Up to 50,000 rows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The CSV file.",
            "schema": {
              "type": "string"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "produces": [
          "text/csv",
          "application/json"
        ]
      }
    },
    "/v1/{number}/contacts/{identity}": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "getContact",
        "summary": "One contact",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "identity",
            "in": "path",
            "required": true,
            "description": "The contact's number (country code first), or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "The contact.",
            "schema": {
              "$ref": "#/definitions/ContactResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Contacts"
        ],
        "operationId": "updateContact",
        "summary": "Change a contact",
        "description": "Needs the 'contacts:manage' scope. The same fields as POST /contacts; only the ones given change.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "identity",
            "in": "path",
            "required": true,
            "description": "The contact's number (country code first), or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ContactInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The contact.",
            "schema": {
              "$ref": "#/definitions/ContactResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Contacts"
        ],
        "operationId": "deleteContact",
        "summary": "Delete a contact record",
        "description": "Needs the 'contacts:manage' scope. The Do Not Call list and the opt-ins are separate records and stay. The contact's appointments (and notes, payments, packages) are kept: add `booking_data=erase` to erase or anonymise them too (future confirmed appointments are cancelled without a message, every appointment loses the customer's name, number, e-mail and notes, and their notes, links, holds and poll votes are deleted; the answer then carries `booking_data_erased` with the counts, and `booking.customer.erased` is sent). That cannot be undone. With `booking_data=erase` the contact's ticket data is erased too (orders and tickets lose the name, number, email and answers; old ticket links stop working); the answer then carries `ticket_data_erased` with the counts and `ticket.buyer.erased` is sent. It is refused, with the reason in `note`, while the contact holds a valid ticket for a coming date.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "identity",
            "in": "path",
            "required": true,
            "description": "The contact's number (country code first), or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "booking_data",
            "in": "query",
            "required": false,
            "description": "erase: also erase the contact's booking data (appointments, notes, links, holds, poll votes, package and payment details). Left out: the appointments are kept.",
            "type": "string",
            "enum": [
              "erase"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/ContactDeleteResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/contacts/{identity}/consent": {
      "post": {
        "tags": [
          "Contacts"
        ],
        "operationId": "recordConsent",
        "summary": "Record consent (or its withdrawal) with evidence",
        "description": "Needs the 'contacts:manage' scope. Makes the contact when it is new. `marketing: false` records a withdrawal: add the contact to the Do Not Call list too. Fires contact.updated.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "identity",
            "in": "path",
            "required": true,
            "description": "The contact's number (country code first), or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Consent"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded.",
            "schema": {
              "$ref": "#/definitions/ContactResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/segments": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "listSegments",
        "summary": "Your segments (saved contact filters)",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The segments.",
            "schema": {
              "$ref": "#/definitions/SegmentsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "g5tnr",
                "segments": [
                  {
                    "id": 12,
                    "name": "VIP, consented",
                    "filter": {
                      "tags_any": [
                        "vip"
                      ],
                      "consent_marketing": true,
                      "last_inbound_days": 90
                    },
                    "contacts": null,
                    "created": "2026-11-02T01:00:00Z",
                    "updated": "2026-11-02T01:00:00Z"
                  }
                ],
                "count": 1
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "operationId": "createSegment",
        "summary": "Save a contact filter as a segment",
        "description": "Needs the 'contacts:manage' scope. Up to 100 segments. Send to it with POST /messages `segment`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SegmentRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created, with how many contacts match now.",
            "schema": {
              "$ref": "#/definitions/SegmentResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/segments/{id}": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "getSegment",
        "summary": "One segment, with how many contacts match now",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The segment's id, or its exact name.",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "The segment.",
            "schema": {
              "$ref": "#/definitions/SegmentResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Contacts"
        ],
        "operationId": "updateSegment",
        "summary": "Rename a segment or replace its filter",
        "description": "Needs the 'contacts:manage' scope. A `filter` given replaces the whole filter.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The segment's id, or its exact name.",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SegmentRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The segment.",
            "schema": {
              "$ref": "#/definitions/SegmentResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Contacts"
        ],
        "operationId": "deleteSegment",
        "summary": "Delete a segment (its contacts stay)",
        "description": "Needs the 'contacts:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The segment's id, or its exact name.",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/SegmentDeleteResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/segments/{id}/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "listSegmentContacts",
        "summary": "The contacts a segment matches now",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The segment's id, or its exact name.",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The contacts.",
            "schema": {
              "$ref": "#/definitions/SegmentContactsResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/compliance/export.csv": {
      "get": {
        "tags": [
          "Do Not Call"
        ],
        "operationId": "exportCompliance",
        "summary": "Consent records, Do Not Call list and opt-ins as one CSV",
        "description": "Needs the 'dnc:manage' scope. One row per record with record_type (consent, do_not_call, opt_in), identity, name, status, time, source, text, note and evidence: the records the Spam Act 2003 expects you to be able to show.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The CSV file.",
            "schema": {
              "type": "string"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "produces": [
          "text/csv",
          "application/json"
        ]
      }
    },
    "/v1/{number}/usage/meta": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsageMeta",
        "summary": "What WhatsApp charges this billing month, per day",
        "description": "The billing month's messages by Meta's pricing category (the 1,000 free service messages, billable service, utility, marketing, authentication) with an indicative cost estimate, in all and per day. From the pricing object of WhatsApp's status webhooks; Meta bills you directly, so treat the amount as a guide.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The counts and the estimate.",
            "schema": {
              "$ref": "#/definitions/UsageMetaResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m7bqs",
                "number": "4976659348270",
                "meta_pricing": {
                  "billing_period": {
                    "start": "2026-10-15T00:00:00Z",
                    "end": "2026-11-15T00:00:00Z"
                  },
                  "counts": {
                    "service_free_used": 412,
                    "service_billable": 0,
                    "utility": 120,
                    "marketing": 35,
                    "authentication": 0,
                    "free_entry_point": 2,
                    "unknown": 3,
                    "total": 572,
                    "estimated_cost_usd": 4.3
                  },
                  "free_service_messages": {
                    "allowance_per_month": 1000,
                    "used": 412,
                    "left": 588
                  },
                  "estimated_cost": {
                    "currency": "USD",
                    "amount": 4.3,
                    "rate_region": "Rest of Asia Pacific (Australia, New Zealand, Japan, ...)",
                    "rate_region_code": "apac",
                    "rates_per_message": {
                      "marketing": 0.0842,
                      "utility": 0.0113,
                      "authentication": 0.0113,
                      "service": 0.0113
                    },
                    "rates_last_checked": "2026-11-02"
                  },
                  "days": [
                    {
                      "date": "2026-11-01",
                      "counts": {
                        "service_free_used": 20,
                        "service_billable": 0,
                        "utility": 5,
                        "marketing": 0,
                        "authentication": 0,
                        "free_entry_point": 0,
                        "unknown": 0,
                        "total": 25,
                        "estimated_cost_usd": 0.0565
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/media/{id}": {
      "get": {
        "tags": [
          "Media"
        ],
        "operationId": "getMedia",
        "summary": "Download a received file (stored copy, else from WhatsApp)",
        "description": "app2email keeps its own copy of every received image, video, audio, document and sticker (WhatsApp's ids expire after 7 days): served first. Without one, the file comes from WhatsApp by the message's media id, or by a WhatsApp media id in the URL. Header X-Media-Source: stored | whatsapp. `?info=true`: type, size and sha256 instead of the file. WhatsApp pauses media lookups after many errors, so an id it did not know is remembered for 30 minutes.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The message_id of a received message (wamid..., URL-encoded), or a WhatsApp media id (digits).",
            "type": "string",
            "x-example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA="
          },
          {
            "name": "info",
            "in": "query",
            "required": false,
            "description": "true: the file's type, size and sha256 as JSON, not the file.",
            "type": "boolean"
          }
        ],
        "responses": {
          "200": {
            "description": "The file (or with ?info=true the JSON info).",
            "schema": {
              "type": "file"
            },
            "headers": {
              "X-Media-Source": {
                "type": "string",
                "description": "stored: app2email's copy. whatsapp: fetched from WhatsApp now."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "produces": [
          "*/*"
        ]
      },
      "delete": {
        "tags": [
          "Media"
        ],
        "operationId": "deleteMedia",
        "summary": "Delete an uploaded file at WhatsApp",
        "description": "The media_id of POST /media (WhatsApp keeps uploads 30 days otherwise). A scheduled send that still uses it then fails. app2email's stored copies of received files stay.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The WhatsApp media id (digits).",
            "type": "string",
            "x-example": "1037543291543636"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/MediaDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d7mdl",
                "media_id": "1037543291543636",
                "deleted": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/approvals": {
      "get": {
        "tags": [
          "Approvals"
        ],
        "operationId": "listApprovals",
        "summary": "Sends held for approval",
        "description": "Sends held by a key's approval gate (approval_above on the API key page): pending ones by default, `status=all` for the resolved and expired ones of the last 7 days too.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "pending (default) or all.",
            "type": "string",
            "enum": [
              "pending",
              "all"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The held sends.",
            "schema": {
              "$ref": "#/definitions/ApprovalsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a4lxc",
                "approvals": [
                  {
                    "id": "apr_a1b2c3d4e5f6g7h8",
                    "status": "pending",
                    "created": "2026-11-02T01:12:09Z",
                    "expires": "2026-11-04T01:12:09Z",
                    "key": "Agent",
                    "request_id": "p3kdm",
                    "recipients": 250,
                    "summary": {
                      "recipients": 250,
                      "to_send": 248,
                      "template": {
                        "name": "november_offer",
                        "language": "en",
                        "category": "MARKETING"
                      },
                      "text": "Hi {{first_name}}, ..."
                    },
                    "url": "https://www.app2email.com/dashboard/approvals?id=apr_a1b2c3d4e5f6g7h8",
                    "approve_url": "https://api.app2email.com/v1/4976659348270/approvals/apr_a1b2c3d4e5f6g7h8/approve"
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/approvals/{id}/approve": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "operationId": "approveSend",
        "summary": "Approve a held send: it is sent now",
        "description": "Needs the 'messages:send' scope, from a key that is not a sandbox key. The stored request is run as a normal send (the Do Not Call list, the limits and the daily cap are checked again); `send` in the answer is the answer the original request would have got. Fires approval.resolved. A held send expires 48 hours after it was held.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The approval's id.",
            "type": "string",
            "x-example": "apr_a1b2c3d4e5f6g7h8"
          }
        ],
        "responses": {
          "200": {
            "description": "Approved and run.",
            "schema": {
              "$ref": "#/definitions/ApprovalResolveResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a5mzd",
                "approval": {
                  "id": "apr_a1b2c3d4e5f6g7h8",
                  "status": "approved",
                  "resolved_by": "api:Manager",
                  "resolved_at": "2026-11-02T02:00:00Z",
                  "result": {
                    "http_status": 200,
                    "status": "accepted",
                    "accepted": 248,
                    "failed": 0,
                    "broadcast_code": "k3XbQ9rTzP2mWv7a1c9e"
                  }
                },
                "send": {
                  "success": true,
                  "status": "accepted",
                  "recipients": 250,
                  "accepted": 248,
                  "failed": 2
                },
                "note": "Approved and sent: 'send' is the answer the original request would have got."
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/approvals/{id}/reject": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "operationId": "rejectSend",
        "summary": "Reject a held send: nothing is sent",
        "description": "Needs the 'messages:send' scope. Fires approval.resolved.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The approval's id.",
            "type": "string",
            "x-example": "apr_a1b2c3d4e5f6g7h8"
          }
        ],
        "responses": {
          "200": {
            "description": "Rejected.",
            "schema": {
              "$ref": "#/definitions/ApprovalResolveResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhooks",
        "summary": "Your webhooks",
        "description": "With the result of the last delivery to each.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The webhooks.",
            "schema": {
              "$ref": "#/definitions/WebhooksResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w3bls",
                "events_available": [
                  "message.status",
                  "message.received",
                  "message.failed",
                  "contact.opted_out",
                  "broadcast.completed",
                  "usage.threshold",
                  "template.status_changed",
                  "conversation.owner_changed",
                  "message.held_for_approval",
                  "approval.resolved",
                  "contact.updated",
                  "waitlist.joined",
                  "waitlist.notified",
                  "waitlist.removed",
                  "booking.created",
                  "booking.cancelled",
                  "booking.rescheduled",
                  "booking.rated",
                  "flow.completed",
                  "booking.updated",
                  "booking.note.created",
                  "calendar.block.created",
                  "calendar.block.deleted",
                  "call.incoming",
                  "call.status",
                  "message.edited",
                  "message.deleted",
                  "contact.changed_number",
                  "number.updated",
                  "number.error",
                  "flow.status_changed",
                  "booking.paid",
                  "booking.refunded",
                  "payment.paid",
                  "package.purchased",
                  "poll.voted",
                  "poll.closed",
                  "booking.customer.erased",
                  "order.created",
                  "order.paid",
                  "order.accepted",
                  "order.ready",
                  "order.completed",
                  "order.cancelled",
                  "order.refunded",
                  "order.no_show",
                  "submission.created",
                  "submission.files_ready",
                  "submission.updated",
                  "submission.status_changed",
                  "submission.assigned",
                  "submission.note_added",
                  "submission.customer_replied",
                  "submission.deleted",
                  "submit.automation_failed",
                  "ticket.order.confirmed",
                  "ticket.order.refunded",
                  "ticket.checked_in",
                  "ticket.passed_on",
                  "ticket.event.sold_out",
                  "ticket.event.cancelled",
                  "ticket.waitlist.joined",
                  "ticket.buyer.erased"
                ],
                "webhooks": [
                  {
                    "id": "wh_a1b2c3d4e5f6g7h8",
                    "url": "https://hooks.example.com/app2email",
                    "events": [
                      "message.status",
                      "message.received",
                      "message.failed",
                      "contact.opted_out",
                      "broadcast.completed",
                      "usage.threshold",
                      "template.status_changed",
                      "conversation.owner_changed",
                      "message.held_for_approval",
                      "approval.resolved",
                      "contact.updated",
                      "waitlist.joined",
                      "waitlist.notified",
                      "waitlist.removed",
                      "booking.created",
                      "booking.cancelled",
                      "booking.rescheduled",
                      "booking.rated",
                      "flow.completed",
                      "booking.updated",
                      "booking.note.created",
                      "calendar.block.created",
                      "calendar.block.deleted",
                      "call.incoming",
                      "call.status",
                      "message.edited",
                      "message.deleted",
                      "contact.changed_number",
                      "number.updated",
                      "number.error",
                      "flow.status_changed",
                      "booking.paid",
                      "booking.refunded",
                      "payment.paid",
                      "package.purchased",
                      "poll.voted",
                      "poll.closed",
                      "booking.customer.erased",
                      "order.created",
                      "order.paid",
                      "order.accepted",
                      "order.ready",
                      "order.completed",
                      "order.cancelled",
                      "order.refunded",
                      "order.no_show",
                      "submission.created",
                      "submission.files_ready",
                      "submission.updated",
                      "submission.status_changed",
                      "submission.assigned",
                      "submission.note_added",
                      "submission.customer_replied",
                      "submission.deleted",
                      "submit.automation_failed",
                      "ticket.order.confirmed",
                      "ticket.order.refunded",
                      "ticket.checked_in",
                      "ticket.passed_on",
                      "ticket.event.sold_out",
                      "ticket.event.cancelled",
                      "ticket.waitlist.joined",
                      "ticket.buyer.erased"
                    ],
                    "secret": "whsec_3Fq9LmZ2xT8pW1rK7vB4nD6sH0jC5yA9",
                    "created": "2026-11-01T09:30:00.000Z",
                    "active": true,
                    "format": "app2email",
                    "headers": {
                      "Authorization": "****YXNz"
                    },
                    "last_delivery": {
                      "at": "2026-11-06T01:00:03.300Z",
                      "ok": true,
                      "result": "HTTP 200 in 184 ms"
                    }
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhook",
        "summary": "Get events at your URL",
        "description": "Up to 5 per number. Every webhook gets every event: use the event's type to pick the ones you handle. The same URL again answers that webhook, turned on (200). The answer has the secret that signs every event. Optional: headers (custom headers) and format (app2email or meta).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/WebhookRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created.",
            "schema": {
              "$ref": "#/definitions/WebhookResponse"
            }
          },
          "200": {
            "description": "This URL already had a webhook: it is on, same id and secret.",
            "schema": {
              "$ref": "#/definitions/WebhookResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/samples": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "webhookSamples",
        "summary": "A sample of every event",
        "description": "Each event type (and ping) as a test of that type sends it: the real fields, with made-up values and \"test\": true. Needs the 'webhooks:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The samples.",
            "schema": {
              "$ref": "#/definitions/WebhookSamplesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w3bsm",
                "samples": {
                  "ping": {
                    "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                    "type": "ping",
                    "created": "2026-11-06T01:00:00.000Z",
                    "number": "4976659348270",
                    "test": true,
                    "data": {
                      "webhook_id": "wh_a1b2c3d4e5f6g7h8",
                      "message": "Test event. If you can see this, your webhook works."
                    }
                  },
                  "message.received": {
                    "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                    "type": "message.received",
                    "created": "2026-11-06T01:00:00.000Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                      "from": "61412345678",
                      "name": "Sample Contact",
                      "type": "text",
                      "text": "Hi, is my order on its way?",
                      "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
                      "timestamp": "2026-11-06T01:00:00.000Z",
                      "from_user_id": "AU.1234567890123456",
                      "whatsapp": {
                        "from": "61412345678",
                        "from_user_id": "AU.1234567890123456",
                        "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                        "timestamp": "1762390800",
                        "type": "text",
                        "text": {
                          "body": "Hi, is my order on its way?"
                        }
                      }
                    },
                    "test": true
                  },
                  "message.status": {
                    "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                    "type": "message.status",
                    "created": "2026-11-06T01:00:00.000Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                      "to": "61412345678",
                      "status": "delivered",
                      "timestamp": "2026-11-06T01:00:00.000Z",
                      "sent_by": "api",
                      "whatsapp_status": "delivered",
                      "recipient_user_id": "AU.1234567890123456",
                      "pricing": {
                        "billable": true,
                        "pricing_model": "PMP",
                        "type": "regular",
                        "category": "utility"
                      },
                      "callback_data": "order-1234"
                    },
                    "test": true
                  }
                },
                "meta_samples": {
                  "message.received": {
                    "object": "whatsapp_business_account",
                    "entry": [
                      {
                        "id": "102290129340398",
                        "changes": [
                          {
                            "field": "messages",
                            "value": {
                              "messaging_product": "whatsapp",
                              "metadata": {
                                "display_phone_number": "4976659348270",
                                "phone_number_id": "106540352242922"
                              },
                              "contacts": [
                                {
                                  "profile": {
                                    "name": "Sample Contact"
                                  },
                                  "wa_id": "61412345678",
                                  "user_id": "AU.1234567890123456"
                                }
                              ],
                              "messages": [
                                {
                                  "from": "61412345678",
                                  "from_user_id": "AU.1234567890123456",
                                  "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                                  "timestamp": "1762390800",
                                  "type": "text",
                                  "text": {
                                    "body": "Hi, is my order on its way?"
                                  }
                                }
                              ]
                            }
                          }
                        ]
                      }
                    ]
                  }
                },
                "note": "What a test of each type sends (POST .../webhooks/{id}/test with {\"type\": \"...\"}). Real events have the same fields, with real values and without \"test\". meta_samples: what a webhook with \"format\": \"meta\" gets instead, for the events that come from WhatsApp."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/{id}": {
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "updateWebhook",
        "summary": "Change a webhook: url, active, headers, format",
        "description": "Only what is given changes: url, active, headers (a header set to null is removed), format. `active: true` turns a webhook back on after it was switched off for failures (and clears the failure count). The same url as another webhook of the number: 409 webhook_url_in_use. Needs the 'webhooks:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/WebhookPatchRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The webhook.",
            "schema": {
              "$ref": "#/definitions/WebhookResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "v3gkx",
                "webhook": {
                  "id": "wh_a1b2c3d4e5f6g7h8",
                  "url": "https://hooks.example.com/app2email",
                  "events": [
                    "message.status",
                    "message.received",
                    "message.failed",
                    "contact.opted_out",
                    "broadcast.completed",
                    "usage.threshold",
                    "template.status_changed",
                    "conversation.owner_changed",
                    "message.held_for_approval",
                    "approval.resolved",
                    "contact.updated",
                    "waitlist.joined",
                    "waitlist.notified",
                    "waitlist.removed",
                    "booking.created",
                    "booking.cancelled",
                    "booking.rescheduled",
                    "booking.rated",
                    "flow.completed",
                    "booking.updated",
                    "booking.note.created",
                    "calendar.block.created",
                    "calendar.block.deleted",
                    "call.incoming",
                    "call.status",
                    "message.edited",
                    "message.deleted",
                    "contact.changed_number",
                    "number.updated",
                    "number.error",
                    "flow.status_changed",
                    "booking.paid",
                    "booking.refunded",
                    "payment.paid",
                    "package.purchased",
                    "poll.voted",
                    "poll.closed",
                    "booking.customer.erased",
                    "order.created",
                    "order.paid",
                    "order.accepted",
                    "order.ready",
                    "order.completed",
                    "order.cancelled",
                    "order.refunded",
                    "order.no_show",
                    "submission.created",
                    "submission.files_ready",
                    "submission.updated",
                    "submission.status_changed",
                    "submission.assigned",
                    "submission.note_added",
                    "submission.customer_replied",
                    "submission.deleted",
                    "submit.automation_failed",
                    "ticket.order.confirmed",
                    "ticket.order.refunded",
                    "ticket.checked_in",
                    "ticket.passed_on",
                    "ticket.event.sold_out",
                    "ticket.event.cancelled",
                    "ticket.waitlist.joined",
                    "ticket.buyer.erased"
                  ],
                  "secret": "whsec_...",
                  "created": "2026-10-20T04:00:00Z",
                  "active": true,
                  "disabled_reason": null,
                  "last_delivery": {
                    "at": "2026-10-26T01:12:11Z",
                    "ok": true,
                    "result": "200"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhook",
        "summary": "Delete a webhook",
        "description": "Stops every delivery to it, planned retries included. Its delivery log is kept 7 days.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/WebhookDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w3bdl",
                "deleted": "wh_a1b2c3d4e5f6g7h8"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "testWebhook",
        "summary": "Send a test event now",
        "description": "Sends a test event to the webhook's URL straight away (once, no retries, not in the delivery log) and answers how the URL responded. No body: a 'ping'. {\"type\": \"message.received\"}: that event's sample. {\"event\": {...}}: your own event. Test events carry \"test\": true and the header X-App2email-Test: true, and are signed like every event. Up to 30 tests an hour per number (429 too_many_tests). A webhook with format meta gets the event as Meta's own body.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/NumberWebhookTestRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The test was made: see 'delivered'.",
            "schema": {
              "$ref": "#/definitions/WebhookTestResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/{id}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "rotateWebhookSecret",
        "summary": "Make a new signing secret",
        "description": "Events are signed with the new secret from then on; the old one stops working at once, unless keep_old_for_hours (1 to 24) is given: the old secret then also signs (a second v1= in X-App2email-Signature) until previous_secret_until. Needs the 'webhooks:manage' scope.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/WebhookRotateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The webhook with its new secret.",
            "schema": {
              "$ref": "#/definitions/WebhookResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "v3gkx",
                "webhook": {
                  "id": "wh_a1b2c3d4e5f6g7h8",
                  "url": "https://hooks.example.com/app2email",
                  "events": [
                    "message.status",
                    "message.received",
                    "message.failed",
                    "contact.opted_out",
                    "broadcast.completed",
                    "usage.threshold",
                    "template.status_changed",
                    "conversation.owner_changed",
                    "message.held_for_approval",
                    "approval.resolved",
                    "contact.updated",
                    "waitlist.joined",
                    "waitlist.notified",
                    "waitlist.removed",
                    "booking.created",
                    "booking.cancelled",
                    "booking.rescheduled",
                    "booking.rated",
                    "flow.completed",
                    "booking.updated",
                    "booking.note.created",
                    "calendar.block.created",
                    "calendar.block.deleted",
                    "call.incoming",
                    "call.status",
                    "message.edited",
                    "message.deleted",
                    "contact.changed_number",
                    "number.updated",
                    "number.error",
                    "flow.status_changed",
                    "booking.paid",
                    "booking.refunded",
                    "payment.paid",
                    "package.purchased",
                    "poll.voted",
                    "poll.closed",
                    "booking.customer.erased",
                    "order.created",
                    "order.paid",
                    "order.accepted",
                    "order.ready",
                    "order.completed",
                    "order.cancelled",
                    "order.refunded",
                    "order.no_show",
                    "submission.created",
                    "submission.files_ready",
                    "submission.updated",
                    "submission.status_changed",
                    "submission.assigned",
                    "submission.note_added",
                    "submission.customer_replied",
                    "submission.deleted",
                    "submit.automation_failed",
                    "ticket.order.confirmed",
                    "ticket.order.refunded",
                    "ticket.checked_in",
                    "ticket.passed_on",
                    "ticket.event.sold_out",
                    "ticket.event.cancelled",
                    "ticket.waitlist.joined",
                    "ticket.buyer.erased"
                  ],
                  "secret": "whsec_...",
                  "created": "2026-10-20T04:00:00Z",
                  "active": true,
                  "disabled_reason": null,
                  "last_delivery": {
                    "at": "2026-10-26T01:12:11Z",
                    "ok": true,
                    "result": "200"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/{id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookDeliveries",
        "summary": "The last deliveries, with every attempt",
        "description": "The events sent to this webhook in the last 7 days (the latest 100), newest first, each with its attempts. Use it to find what failed.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "failed: never delivered. delivered: delivered.",
            "type": "string",
            "enum": [
              "failed",
              "delivered"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The deliveries.",
            "schema": {
              "$ref": "#/definitions/WebhookDeliveriesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p0fsa",
                "deliveries": [
                  {
                    "event_id": "evt_Xq3k9m2",
                    "type": "message.status",
                    "created": "2026-10-26T01:12:11Z",
                    "delivered": false,
                    "attempts": [
                      {
                        "at": "2026-10-26T01:12:11Z",
                        "ok": false,
                        "http_status": 503,
                        "ms": 2001,
                        "error": "timeout"
                      },
                      {
                        "at": "2026-10-26T01:12:21Z",
                        "ok": false,
                        "http_status": 503,
                        "ms": 1995,
                        "error": "timeout"
                      }
                    ]
                  }
                ],
                "note": "The last 100 deliveries of the last 7 days."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/{id}/deliveries/{event_id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookDelivery",
        "summary": "One delivery, with the event as it was sent",
        "description": "Every try, and next_attempt_at while a retry is planned. event_body only with a key that also has messages:read.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          },
          {
            "name": "event_id",
            "in": "path",
            "required": true,
            "description": "The event's id (X-App2email-Delivery, or 'id' in the event).",
            "type": "string",
            "x-example": "evt_Xq3k9m2"
          }
        ],
        "responses": {
          "200": {
            "description": "The delivery.",
            "schema": {
              "$ref": "#/definitions/WebhookDeliveryResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "y5wdn",
                "delivery": {
                  "event_id": "evt_Xq3k9m2",
                  "type": "message.status",
                  "created": "2026-10-26T01:12:11Z",
                  "delivered": false,
                  "attempts": [
                    {
                      "at": "2026-10-26T01:12:11Z",
                      "ok": false,
                      "http_status": 503,
                      "ms": 2001,
                      "error": "timeout"
                    }
                  ],
                  "event_body": {
                    "id": "evt_Xq3k9m2",
                    "type": "message.status",
                    "created": "2026-10-26T01:12:11Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                      "to": "61412345678",
                      "status": "delivered",
                      "timestamp": "2026-10-26T01:12:11Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/{id}/deliveries/{event_id}/redeliver": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "redeliverWebhookEvent",
        "summary": "Send a stored event again",
        "description": "The same event (same id, same body) is sent to the webhook's URL once, now, and the answer says how the URL responded. Needs the 'webhooks:manage' scope. An event that is being sent right now (its first try or a planned retry): 409 delivery_in_progress. Delivered: no more planned retries.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The webhook's id.",
            "type": "string",
            "x-example": "wh_a1b2c3d4e5f6g7h8"
          },
          {
            "name": "event_id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "type": "string",
            "x-example": "evt_Xq3k9m2"
          }
        ],
        "responses": {
          "200": {
            "description": "The answer of the URL.",
            "schema": {
              "$ref": "#/definitions/WebhookRedeliverResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "z8rjh",
                "delivered": true,
                "http_status": 200,
                "response_ms": 180,
                "error": null
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/analytics/pricing": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "operationId": "getPricingAnalytics",
        "summary": "WhatsApp cost and volume of this number",
        "description": "Meta's pricing_analytics for this number: delivered messages and their cost per period. Estimates, not the invoice.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Start, ISO 8601. Default: 30 days before until. At most 1 year back.",
            "type": "string",
            "x-example": "2026-10-01T00:00:00Z"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "End, ISO 8601. Default: now.",
            "type": "string",
            "x-example": "2026-11-01T00:00:00Z"
          },
          {
            "name": "granularity",
            "in": "query",
            "required": false,
            "description": "Default day.",
            "type": "string",
            "enum": [
              "half_hour",
              "day",
              "month"
            ],
            "default": "day"
          },
          {
            "name": "countries",
            "in": "query",
            "required": false,
            "description": "Only these countries: comma separated 2-letter codes.",
            "type": "string",
            "x-example": "DE,AT"
          },
          {
            "name": "dimensions",
            "in": "query",
            "required": false,
            "description": "Break down by: comma separated category, type, country, tier, phone. Default category,type.",
            "type": "string",
            "x-example": "category,type,country"
          }
        ],
        "responses": {
          "200": {
            "description": "The data points.",
            "schema": {
              "$ref": "#/definitions/PricingAnalyticsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a2p4r",
                "since": "2026-10-01T00:00:00.000Z",
                "until": "2026-10-03T00:00:00.000Z",
                "granularity": "day",
                "currency": "EUR",
                "data_points": [
                  {
                    "start": "2026-10-01T00:00:00.000Z",
                    "end": "2026-10-02T00:00:00.000Z",
                    "pricing_category": "MARKETING",
                    "pricing_type": "REGULAR",
                    "volume": 120,
                    "cost": 15.6
                  },
                  {
                    "start": "2026-10-01T00:00:00.000Z",
                    "end": "2026-10-02T00:00:00.000Z",
                    "pricing_category": "SERVICE",
                    "pricing_type": "FREE_CUSTOMER_SERVICE",
                    "volume": 41,
                    "cost": 0
                  },
                  {
                    "start": "2026-10-02T00:00:00.000Z",
                    "end": "2026-10-03T00:00:00.000Z",
                    "pricing_category": "UTILITY",
                    "pricing_type": "REGULAR",
                    "volume": 300,
                    "cost": 6.9
                  }
                ],
                "totals": {
                  "volume": 461,
                  "cost": 22.5
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/analytics/messages": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "operationId": "getMessageAnalytics",
        "summary": "Messages sent and delivered, as WhatsApp counts them",
        "description": "Meta's analytics for this number, per period.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Start, ISO 8601. Default: 30 days before until. At most 1 year back.",
            "type": "string",
            "x-example": "2026-10-01T00:00:00Z"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "End, ISO 8601. Default: now.",
            "type": "string",
            "x-example": "2026-11-01T00:00:00Z"
          },
          {
            "name": "granularity",
            "in": "query",
            "required": false,
            "description": "Default day.",
            "type": "string",
            "enum": [
              "half_hour",
              "day",
              "month"
            ],
            "default": "day"
          },
          {
            "name": "countries",
            "in": "query",
            "required": false,
            "description": "Only these countries: comma separated 2-letter codes.",
            "type": "string",
            "x-example": "DE,AT"
          }
        ],
        "responses": {
          "200": {
            "description": "The data points.",
            "schema": {
              "$ref": "#/definitions/MessageAnalyticsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a3m5s",
                "since": "2026-10-01T00:00:00.000Z",
                "until": "2026-10-03T00:00:00.000Z",
                "granularity": "day",
                "data_points": [
                  {
                    "start": "2026-10-01T00:00:00.000Z",
                    "end": "2026-10-02T00:00:00.000Z",
                    "sent": 161,
                    "delivered": 155
                  },
                  {
                    "start": "2026-10-02T00:00:00.000Z",
                    "end": "2026-10-03T00:00:00.000Z",
                    "sent": 300,
                    "delivered": 291
                  }
                ],
                "totals": {
                  "sent": 461,
                  "delivered": 446
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/activity": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "operationId": "getAccountActivity",
        "summary": "The WhatsApp Business Account's activity log",
        "description": "Newest first: registrations, PIN and partner changes, billing, templates. Covers every number on the WABA.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100, default 25).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 25
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The activities.",
            "schema": {
              "$ref": "#/definitions/AccountActivityResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a4c6t",
                "activities": [
                  {
                    "id": "1234567890123",
                    "event_type": "PHONE_NUMBER_REGISTERED_ON_CLOUD_API",
                    "category": "PHONE_NUMBER",
                    "actor_id": "61550000000001",
                    "time": "2026-11-05T22:14:03.000Z"
                  },
                  {
                    "id": "1234567890122",
                    "event_type": "TWO_STEP_VERIFICATION_PIN_CHANGED",
                    "category": "PHONE_NUMBER",
                    "actor_id": "61550000000001",
                    "time": "2026-11-05T22:13:40.000Z"
                  }
                ],
                "count": 2,
                "next_cursor": "QVFIUmFfVEhuS2xOZA"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversions/dataset": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "operationId": "getConversionsDataset",
        "summary": "The Conversions API dataset of the account",
        "description": "404 dataset_not_found: create it first.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The dataset.",
            "schema": {
              "$ref": "#/definitions/ConversionsDatasetResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a5d7u",
                "dataset": {
                  "id": "1265431020859743",
                  "name": "WhatsApp conversions"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Analytics"
        ],
        "operationId": "createConversionsDataset",
        "summary": "Create the Conversions API dataset",
        "description": "One per WhatsApp Business Account. Answer 201.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/ConversionsDatasetRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created.",
            "schema": {
              "$ref": "#/definitions/ConversionsDatasetResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a6e8v",
                "dataset": {
                  "id": "1265431020859743",
                  "name": "WhatsApp conversions"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversions/dataset/quality": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "operationId": "getConversionsDatasetQuality",
        "summary": "Quality of the Conversions API dataset",
        "description": "Meta's dataset quality: event match quality, coverage, freshness. fields: Meta's field list (default: all of these).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Meta's field list, eg web{event_match_quality,event_name}.",
            "type": "string",
            "x-example": "web{event_match_quality{composite_score},event_name}"
          },
          {
            "name": "agent_name",
            "in": "query",
            "required": false,
            "description": "Only the events a partner integration sent.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Meta's figures.",
            "schema": {
              "$ref": "#/definitions/DatasetQualityResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a8g0x",
                "dataset_id": "1265431020859743",
                "quality": {
                  "web": [
                    {
                      "event_name": "Purchase",
                      "event_match_quality": {
                        "composite_score": 6.2,
                        "match_key_feedback": [
                          {
                            "identifier": "ctwa_clid",
                            "coverage": {
                              "percentage": 92.5
                            }
                          }
                        ]
                      },
                      "event_coverage": {
                        "percentage": 71.3
                      },
                      "data_freshness": {
                        "upload_frequency": "real_time"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/conversions/events": {
      "post": {
        "tags": [
          "Analytics"
        ],
        "operationId": "sendConversionEvents",
        "summary": "Send conversion events of WhatsApp chats",
        "description": "Up to 1,000 events to the account's dataset (eg a Purchase after a click-to-WhatsApp ad). Defaults: action_source, messaging_channel, the WABA id.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ConversionEventsRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Taken by Meta.",
            "schema": {
              "$ref": "#/definitions/ConversionEventsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a7f9w",
                "dataset_id": "1265431020859743",
                "events_received": 1,
                "fbtrace_id": "AbCdEfGh1234"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/waitlist": {
      "get": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "listBookingWaitlist",
        "summary": "The waitlist of full days",
        "description": "Scope: `bookings:manage` (or `messages:read`). The customers waiting for a time, soonest day first, oldest entry first. Active entries (pending_confirm, waiting, notified) unless include_closed. When a time frees up (a cancellation, a move, a removed time block, and every 5 minutes) the waiting customers of that day get a WhatsApp message with a link to book it; the first booking wins. 409 `waitlist_not_set_up` while the waitlist is not available on the server.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "The first day, YYYY-MM-DD in the business time zone. Default today.",
            "type": "string",
            "x-example": "2026-11-13"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "The last day (included). Default from + 60 days; at most 366 days.",
            "type": "string",
            "x-example": "2026-12-31"
          },
          {
            "name": "service_id",
            "in": "query",
            "required": false,
            "description": "Only this service.",
            "type": "string"
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "Only this customer (number with country code, digits only, or business-scoped user id).",
            "type": "string"
          },
          {
            "name": "include_closed",
            "in": "query",
            "required": false,
            "description": "true: also booked, expired and removed entries.",
            "type": "boolean"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "At most this many entries (1 to 1000, default 500).",
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          }
        ],
        "responses": {
          "200": {
            "description": "The entries.",
            "schema": {
              "$ref": "#/definitions/WaitlistListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w1lst",
                "entries": [
                  {
                    "id": 12,
                    "reference": "WL-4HT9XC",
                    "status": "waiting",
                    "service_id": "haircut",
                    "service_name": "Haircut",
                    "provider_id": "maria",
                    "provider_name": "Maria",
                    "date": "2026-11-20",
                    "date_label": "Fri 20 Nov 2026",
                    "slot_id": "",
                    "time_label": "",
                    "contact": "61412345678",
                    "contact_name": "Jane",
                    "contact_email": "",
                    "seats": 1,
                    "source": "api",
                    "notified_count": 0,
                    "notified_at": null,
                    "appointment_id": null,
                    "note": "",
                    "created": "2026-11-13T01:00:00.000Z",
                    "updated": "2026-11-13T01:00:00.000Z",
                    "day": "2026-11-20",
                    "slot_local": "",
                    "contact_masked": "•••• 5678",
                    "created_at": "2026-11-13T01:00:00.000Z"
                  }
                ],
                "count": 1,
                "from": "2026-11-13",
                "to": "2027-01-12",
                "timezone": "Australia/Sydney"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "addToBookingWaitlist",
        "summary": "Put a customer on the waitlist of a full day",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The service must have its waitlist on, the day must be bookable and have no free time left (or the group time in slot_id must be full) - force: true skips the free-time check. One active entry per customer, service and day: asking again answers 200 with that entry (existing: true). Sends `waitlist.joined`. The customer is offered a time when one opens.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/WaitlistRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "On the waitlist.",
            "schema": {
              "$ref": "#/definitions/WaitlistEntryResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w2add",
                "entry": {
                  "id": 12,
                  "reference": "WL-4HT9XC",
                  "status": "waiting",
                  "service_id": "haircut",
                  "service_name": "Haircut",
                  "provider_id": "maria",
                  "provider_name": "Maria",
                  "date": "2026-11-20",
                  "date_label": "Fri 20 Nov 2026",
                  "slot_id": "",
                  "time_label": "",
                  "contact": "61412345678",
                  "contact_name": "Jane",
                  "contact_email": "",
                  "seats": 1,
                  "source": "api",
                  "notified_count": 0,
                  "notified_at": null,
                  "appointment_id": null,
                  "note": "",
                  "created": "2026-11-13T01:00:00.000Z",
                  "updated": "2026-11-13T01:00:00.000Z",
                  "day": "2026-11-20",
                  "slot_local": "",
                  "contact_masked": "•••• 5678",
                  "created_at": "2026-11-13T01:00:00.000Z"
                },
                "existing": false
              }
            }
          },
          "200": {
            "description": "Already on the waitlist (existing: true).",
            "schema": {
              "$ref": "#/definitions/WaitlistEntryResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w2add",
                "entry": {
                  "id": 12,
                  "reference": "WL-4HT9XC",
                  "status": "waiting",
                  "service_id": "haircut",
                  "service_name": "Haircut",
                  "provider_id": "maria",
                  "provider_name": "Maria",
                  "date": "2026-11-20",
                  "date_label": "Fri 20 Nov 2026",
                  "slot_id": "",
                  "time_label": "",
                  "contact": "61412345678",
                  "contact_name": "Jane",
                  "contact_email": "",
                  "seats": 1,
                  "source": "api",
                  "notified_count": 0,
                  "notified_at": null,
                  "appointment_id": null,
                  "note": "",
                  "created": "2026-11-13T01:00:00.000Z",
                  "updated": "2026-11-13T01:00:00.000Z",
                  "day": "2026-11-20",
                  "slot_local": "",
                  "contact_masked": "•••• 5678",
                  "created_at": "2026-11-13T01:00:00.000Z"
                },
                "existing": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/waitlist/{reference}/remove": {
      "post": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "removeFromBookingWaitlist",
        "summary": "Take a customer off the waitlist",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The customer is not messaged. Sends `waitlist.removed`. An entry that is already closed answers 200 as it is.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "description": "The entry's reference (or its id).",
            "type": "string",
            "x-example": "WL-4HT9XC"
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "schema": {
              "$ref": "#/definitions/WaitlistEntryResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "w3rem",
                "entry": {
                  "id": 12,
                  "reference": "WL-4HT9XC",
                  "status": "removed",
                  "service_id": "haircut",
                  "service_name": "Haircut",
                  "provider_id": "maria",
                  "provider_name": "Maria",
                  "date": "2026-11-20",
                  "date_label": "Fri 20 Nov 2026",
                  "slot_id": "",
                  "time_label": "",
                  "contact": "61412345678",
                  "contact_name": "Jane",
                  "contact_email": "",
                  "seats": 1,
                  "source": "api",
                  "notified_count": 0,
                  "notified_at": null,
                  "appointment_id": null,
                  "note": "",
                  "created": "2026-11-13T01:00:00.000Z",
                  "updated": "2026-11-13T01:00:00.000Z",
                  "day": "2026-11-20",
                  "slot_local": "",
                  "contact_masked": "•••• 5678",
                  "created_at": "2026-11-13T01:00:00.000Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings": {
      "get": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "listBookings",
        "summary": "The appointments, soonest start first",
        "description": "Scope: `bookings:manage` (or `messages:read`). Booked on WhatsApp, from the dashboard or through the API. Filter by a range of days (business time zone) or times, a status, or one contact; `order=desc` for the latest start first. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Only appointments starting at or after this day (YYYY-MM-DD, business time zone) or ISO 8601 time.",
            "type": "string",
            "x-example": "2026-11-10"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Only appointments starting on or before this day (YYYY-MM-DD, included) or before this ISO 8601 time.",
            "type": "string",
            "x-example": "2026-11-16"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only this status.",
            "type": "string",
            "enum": [
              "confirmed",
              "cancelled",
              "completed",
              "no_show"
            ]
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "Only this customer (number with country code, or business-scoped user id).",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "provider_id",
            "in": "query",
            "required": false,
            "description": "Only this staff member's appointments (GET /bookings/staff).",
            "type": "string",
            "x-example": "maria"
          },
          {
            "name": "upcoming",
            "in": "query",
            "required": false,
            "description": "true: confirmed appointments starting now or later, soonest first (status, from, to and order are then ignored).",
            "type": "boolean",
            "default": false
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Appointments whose customer name, reference or number contains this text.",
            "type": "string",
            "x-example": "smith"
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc: soonest start first (default). desc: latest start first.",
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The appointments.",
            "schema": {
              "$ref": "#/definitions/BookingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "b1kq2",
                "bookings": [
                  {
                    "id": 42,
                    "reference": "BK-7Q3M2A",
                    "status": "confirmed",
                    "contact": "61412345678",
                    "contact_name": "John Smith",
                    "contact_email": "john@example.com",
                    "service": {
                      "id": "haircut",
                      "name": "Haircut",
                      "duration_min": 30
                    },
                    "start": "2026-11-09T22:00:00.000Z",
                    "end": "2026-11-09T22:30:00.000Z",
                    "timezone": "Australia/Sydney",
                    "source": "api",
                    "calendar": {
                      "provider": "google",
                      "event_id": "evt_1a2b3c",
                      "url": "https://calendar.google.com/calendar/event?eid=..."
                    },
                    "answers": {},
                    "notes": "First visit",
                    "provider": {
                      "id": "maria",
                      "name": "Maria"
                    },
                    "credits_used": 0,
                    "created": "2026-11-06T01:12:09.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1,
                "order": "asc",
                "enabled": true,
                "timezone": "Australia/Sydney"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "createBooking",
        "summary": "Book an appointment for a customer at a free slot",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The slot must be one of GET /bookings/availability (on the grid, inside the hours, free; the business's own minimum notice does not apply). The customer gets the confirmation on WhatsApp (a text with a calendar file inside their 24 hour window, else the booking confirmation template) unless `notify` is false; the business gets an email, the calendar event is written, and `booking.created` is sent (with `hold: true` when made from a hold). 409 `booking_slot_taken` when the time went meanwhile. To book a time kept with POST /bookings/holds, send its `hold` reference. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Booked.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "b2mz7",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "confirmed",
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "contact_email": "john@example.com",
                  "service": {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30
                  },
                  "start": "2026-11-09T22:00:00.000Z",
                  "end": "2026-11-09T22:30:00.000Z",
                  "timezone": "Australia/Sydney",
                  "source": "api",
                  "calendar": {
                    "provider": "google",
                    "event_id": "evt_1a2b3c",
                    "url": "https://calendar.google.com/calendar/event?eid=..."
                  },
                  "answers": {},
                  "notes": "First visit",
                  "provider": {
                    "id": "maria",
                    "name": "Maria"
                  },
                  "credits_used": 0,
                  "created": "2026-11-06T01:12:09.000Z"
                },
                "note": "Booked. The customer gets the confirmation on WhatsApp (a text inside their 24 hour window, else the booking confirmation template)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/availability": {
      "get": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "getBookingAvailability",
        "summary": "The free slots per day for a service, as the customer would see them",
        "description": "Scope: `bookings:manage` (or `messages:read`). Every day of the range (at most 32 days, default today + 6) with its free start times: the opening hours, the closed days, the booked appointments and the calendar's busy time applied. Each slot's `id` is the local time `POST /bookings` takes as `start`. With staff members, `providers` names who is free; `provider_id` asks for one member's own availability.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "service_id",
            "in": "query",
            "required": false,
            "description": "The service (config.services[].id).",
            "type": "string",
            "x-example": "haircut"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "The first day, YYYY-MM-DD in the business time zone. Default today.",
            "type": "string",
            "x-example": "2026-11-10"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "The last day (included). Default from + 6 days; at most 32 days.",
            "type": "string",
            "x-example": "2026-11-16"
          },
          {
            "name": "provider_id",
            "in": "query",
            "required": false,
            "description": "One staff member's own availability (config.providers[].id). Left out: anyone available.",
            "type": "string",
            "x-example": "maria"
          },
          {
            "name": "addons",
            "in": "query",
            "required": false,
            "description": "A comma list of the service's add-on ids: the slots are long enough for them.",
            "type": "string",
            "x-example": "deep,trim"
          },
          {
            "name": "seats",
            "in": "query",
            "required": false,
            "description": "The places wanted on a group time (1 + guests): only times with that many places left.",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 1
          }
        ],
        "responses": {
          "200": {
            "description": "The days and their slots.",
            "schema": {
              "$ref": "#/definitions/AvailabilityResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a9xw1",
                "timezone": "Australia/Sydney",
                "enabled": true,
                "days": [
                  {
                    "date": "2026-11-10",
                    "slots": [
                      {
                        "id": "2026-11-10T09:00",
                        "title": "9:00 AM",
                        "start": "2026-11-09T22:00:00.000Z",
                        "end": "2026-11-09T22:30:00.000Z",
                        "providers": [
                          "maria",
                          "tom"
                        ]
                      },
                      {
                        "id": "2026-11-10T09:30",
                        "title": "9:30 AM",
                        "start": "2026-11-09T22:30:00.000Z",
                        "end": "2026-11-09T23:00:00.000Z",
                        "providers": [
                          "tom"
                        ]
                      }
                    ]
                  },
                  {
                    "date": "2026-11-11",
                    "slots": []
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/reports": {
      "get": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "getBookingReports",
        "summary": "The booking report of a range of days",
        "description": "Scope: `bookings:manage` (or `messages:read`). Over the appointments whose START is in the range (days in the business time zone): totals (bookings, upcoming, completed, cancelled and by the customer, no-shows, the no-show and cancel rates, new and returning customers, revenue and refunds in minor units, the average days booked ahead, the online share), per day, per weekday and hour, per service, staff member and source, and the waitlist numbers. Revenue = online payments of those appointments, less refunds. The range: from / to (at most 366 days), or days (the last N days up to today; default 30). With days=7, 30 or 90 (or nothing) the answer also has the keys of the older report (bookings, completed, cancelled, no_shows, csat, reminders_sent, sessions, top_services, per_provider, nudges). `format=csv`: one line per appointment (reference, date, time, service, staff, customer name, customer phone, status, source, price, paid, add-ons, guests, series, answers); `format=csv_summary`: the older metric,value lines.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "The first day, YYYY-MM-DD in the business time zone.",
            "type": "string",
            "x-example": "2026-11-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "The last day (included). With from alone: from + 29 days.",
            "type": "string",
            "x-example": "2026-11-30"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Instead of from / to: the last N days up to today (1 to 366; 7, 30 or 90 also give the older keys). Default 30.",
            "type": "integer",
            "minimum": 1,
            "maximum": 366,
            "default": 30
          },
          {
            "name": "service_id",
            "in": "query",
            "required": false,
            "description": "Only this service (service is taken too).",
            "type": "string"
          },
          {
            "name": "provider_id",
            "in": "query",
            "required": false,
            "description": "Only this staff member (provider is taken too).",
            "type": "string"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "csv: one line per appointment. csv_summary: the older metric,value lines.",
            "type": "string",
            "enum": [
              "json",
              "csv",
              "csv_summary"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The report.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "r5mpk",
                "days": 30,
                "from": "2026-10-07T01:00:00.000Z",
                "to": "2026-11-06T01:00:00.000Z",
                "bookings": {
                  "total": 48,
                  "by_source": {
                    "whatsapp_flow": 40,
                    "dashboard": 5,
                    "api": 3
                  }
                },
                "completed": 39,
                "cancelled": {
                  "total": 4,
                  "by": {
                    "customer": 3,
                    "business": 1
                  }
                },
                "no_shows": 2,
                "no_show_rate": 0.0488,
                "csat": {
                  "average": 4.6,
                  "responses": 21
                },
                "reminders_sent": 41,
                "sessions": {
                  "started": 62,
                  "completed": 40,
                  "conversion": 0.6452
                },
                "top_services": [
                  {
                    "id": "haircut",
                    "name": "Haircut",
                    "count": 30
                  },
                  {
                    "id": "colour",
                    "name": "Colour",
                    "count": 18
                  }
                ],
                "per_provider": [
                  {
                    "id": "maria",
                    "name": "Maria",
                    "count": 28
                  },
                  {
                    "id": "tom",
                    "name": "Tom",
                    "count": 20
                  }
                ],
                "nudges": {
                  "rebook": 9
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "produces": [
          "text/csv",
          "application/json"
        ]
      }
    },
    "/v1/{number}/bookings/{id}": {
      "get": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "getBooking",
        "summary": "One appointment, by id or reference",
        "description": "Scope: `bookings:manage` (or `messages:read`).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          }
        ],
        "responses": {
          "200": {
            "description": "The appointment.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "b8sva",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "confirmed",
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "contact_email": "john@example.com",
                  "service": {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30
                  },
                  "start": "2026-11-09T22:00:00.000Z",
                  "end": "2026-11-09T22:30:00.000Z",
                  "timezone": "Australia/Sydney",
                  "source": "api",
                  "calendar": {
                    "provider": "google",
                    "event_id": "evt_1a2b3c",
                    "url": "https://calendar.google.com/calendar/event?eid=..."
                  },
                  "answers": {},
                  "notes": "First visit",
                  "provider": {
                    "id": "maria",
                    "name": "Maria"
                  },
                  "credits_used": 0,
                  "created": "2026-11-06T01:12:09.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Calendar"
        ],
        "operationId": "updateBooking",
        "summary": "Change an appointment's details",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The customer's `name` or `email`, the `notes`, the `answers` and the staff member (`provider_id`: the time must be free for the new one, else 409 `booking_slot_taken`; the calendar event moves too). The time is changed with POST /bookings/{id}/reschedule. `booking.updated` is sent with `changed` naming the fields.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingPatchRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c9bp1",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "confirmed",
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "contact_email": "john@example.com",
                  "service": {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30
                  },
                  "start": "2026-11-11T23:00:00.000Z",
                  "end": "2026-11-11T23:30:00.000Z",
                  "timezone": "Australia/Sydney",
                  "source": "api",
                  "calendar": {
                    "provider": "google",
                    "event_id": "evt_1a2b3c",
                    "url": null,
                    "error": null
                  },
                  "answers": {},
                  "notes": "First visit",
                  "provider": {
                    "id": "maria",
                    "name": "Maria"
                  },
                  "credits_used": 0,
                  "link_id": null,
                  "notes_count": 1,
                  "created": "2026-11-06T01:12:09.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/{id}/cancel": {
      "post": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "cancelBooking",
        "summary": "Cancel an appointment",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The calendar event is removed, `booking.cancelled` is sent, and the customer is told on WhatsApp (a text inside their 24 hour window, else the cancellation template) unless `notify` is false. 409 `booking_cancelled` when it already was.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/BookingCancelRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "b3nd4",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "cancelled",
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "contact_email": "john@example.com",
                  "service": {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30
                  },
                  "start": "2026-11-09T22:00:00.000Z",
                  "end": "2026-11-09T22:30:00.000Z",
                  "timezone": "Australia/Sydney",
                  "source": "api",
                  "calendar": {
                    "provider": "google",
                    "event_id": "evt_1a2b3c",
                    "url": "https://calendar.google.com/calendar/event?eid=..."
                  },
                  "answers": {},
                  "notes": "First visit",
                  "provider": {
                    "id": "maria",
                    "name": "Maria"
                  },
                  "credits_used": 0,
                  "created": "2026-11-06T01:12:09.000Z",
                  "cancelled": {
                    "at": "2026-11-07T03:00:00.000Z",
                    "by": "api",
                    "reason": "customer asked by phone"
                  }
                },
                "note": "Cancelled. The customer is told on WhatsApp (a text inside their 24 hour window, else the cancellation template)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/{id}/status": {
      "post": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "setBookingStatus",
        "summary": "Mark an appointment completed, a no-show, or back to confirmed",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Completed appointments get the follow-up message (aftercare and the rating buttons) when the business turned it on; the reports count both. An appointment that is not marked is completed by itself 24 hours after its end. A cancelled appointment cannot be marked (409 `booking_cancelled`).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingStatusRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Marked.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "b9twc",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "completed",
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "contact_email": "john@example.com",
                  "service": {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30
                  },
                  "start": "2026-11-09T22:00:00.000Z",
                  "end": "2026-11-09T22:30:00.000Z",
                  "timezone": "Australia/Sydney",
                  "source": "api",
                  "calendar": {
                    "provider": "google",
                    "event_id": "evt_1a2b3c",
                    "url": "https://calendar.google.com/calendar/event?eid=..."
                  },
                  "answers": {},
                  "notes": "First visit",
                  "provider": {
                    "id": "maria",
                    "name": "Maria"
                  },
                  "credits_used": 0,
                  "created": "2026-11-06T01:12:09.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/booking": {
      "get": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "getBookingSettings",
        "summary": "The booking settings, the default Flow's status and every Flow",
        "description": "Scope: `bookings:manage` (or `messages:read`). Every key of the configuration with its value (defaults filled in): the trigger words, the hours, the services, the messages, the calendar, the staff members; plus the number's Book-and-Pay Flows (as booking_flow in GET /flows).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The settings.",
            "schema": {
              "$ref": "#/definitions/BookingSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s4bkg",
                "enabled": true,
                "configured": true,
                "timezone": "Australia/Sydney",
                "key_status": "valid",
                "validation": [],
                "config": {
                  "trigger": {
                    "keywords": [
                      "book",
                      "booking",
                      "appointment",
                      "reserve",
                      "reservation",
                      "schedule"
                    ],
                    "new_contact": false,
                    "cancel_keywords": [
                      "cancel"
                    ],
                    "reschedule_keywords": [
                      "reschedule",
                      "change booking"
                    ],
                    "other_words_limit": 10,
                    "intro_text": "Tap the button below to choose a time that suits you.",
                    "cta": "Book now",
                    "header": "",
                    "footer": ""
                  },
                  "schedule": {
                    "timezone": "Australia/Sydney",
                    "hours": {
                      "mon": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "tue": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "wed": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "thu": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "fri": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "sat": [],
                      "sun": []
                    },
                    "slot_interval_min": 30,
                    "buffer_before_min": 0,
                    "buffer_after_min": 0,
                    "min_notice_min": 120,
                    "max_advance_days": 30,
                    "max_per_slot": 1,
                    "overrides": []
                  },
                  "services": [
                    {
                      "id": "haircut",
                      "name": "Haircut",
                      "duration_min": 30,
                      "description": "",
                      "price": "$40",
                      "enabled": true
                    }
                  ],
                  "details": {
                    "ask_email": true,
                    "ask_notes": true
                  },
                  "messages": {
                    "business_name": "",
                    "location": "12 Example St, Sydney",
                    "confirmation_text": "You're booked: {service} on {date} at {time} ({duration} min). Reference {reference}. Reply CANCEL if your plans change.",
                    "send_ics": true,
                    "notify_email": ""
                  },
                  "calendar": {
                    "provider": "google",
                    "write_calendar_id": "primary",
                    "busy_calendar_ids": [],
                    "event_title": "{service} - {name}",
                    "event_description": "Booked on WhatsApp.\nPhone: +{phone}\nReference: {reference}\n{notes}"
                  },
                  "providers": []
                },
                "flow": {
                  "key": "booking",
                  "name": "Appointment booking",
                  "kind": "booking",
                  "enabled": true,
                  "is_default": true,
                  "trigger_keywords": [],
                  "id": "1234567890123456",
                  "status": "published",
                  "can_send": true,
                  "health": "AVAILABLE",
                  "last_published_at": "2026-11-06T00:00:00Z",
                  "updated_at": "2026-11-06T00:00:00.000Z"
                },
                "flows": [
                  {
                    "key": "booking",
                    "name": "Appointment booking",
                    "kind": "booking",
                    "enabled": true,
                    "is_default": true,
                    "trigger_keywords": [],
                    "id": "1234567890123456",
                    "status": "published",
                    "can_send": true,
                    "health": "AVAILABLE",
                    "last_published_at": "2026-11-06T00:00:00Z",
                    "updated_at": "2026-11-06T00:00:00.000Z"
                  }
                ]
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "updateBookingSettings",
        "summary": "Switch Book-and-Pay on or off and change the settings",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. `config` is partial: a section object is merged key by key into the stored section, a list (services, providers, schedule.overrides) or a single value replaces what is stored. The whole result is checked against the rules of every section (400 `invalid_setting` with `details.problems`; nothing is saved then). Switching Book-and-Pay on also creates the utility templates bookings send outside the 24 hour window (Meta reviews them).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingSettingsUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved: the settings as they are now.",
            "schema": {
              "$ref": "#/definitions/BookingSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s4bkg",
                "enabled": true,
                "configured": true,
                "timezone": "Australia/Sydney",
                "key_status": "valid",
                "validation": [],
                "config": {
                  "trigger": {
                    "keywords": [
                      "book",
                      "booking",
                      "appointment",
                      "reserve",
                      "reservation",
                      "schedule"
                    ],
                    "new_contact": false,
                    "cancel_keywords": [
                      "cancel"
                    ],
                    "reschedule_keywords": [
                      "reschedule",
                      "change booking"
                    ],
                    "other_words_limit": 10,
                    "intro_text": "Tap the button below to choose a time that suits you.",
                    "cta": "Book now",
                    "header": "",
                    "footer": ""
                  },
                  "schedule": {
                    "timezone": "Australia/Sydney",
                    "hours": {
                      "mon": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "tue": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "wed": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "thu": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "fri": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ],
                      "sat": [],
                      "sun": []
                    },
                    "slot_interval_min": 30,
                    "buffer_before_min": 0,
                    "buffer_after_min": 0,
                    "min_notice_min": 120,
                    "max_advance_days": 30,
                    "max_per_slot": 1,
                    "overrides": []
                  },
                  "services": [
                    {
                      "id": "haircut",
                      "name": "Haircut",
                      "duration_min": 30,
                      "description": "",
                      "price": "$40",
                      "enabled": true
                    }
                  ],
                  "details": {
                    "ask_email": true,
                    "ask_notes": true
                  },
                  "messages": {
                    "business_name": "",
                    "location": "12 Example St, Sydney",
                    "confirmation_text": "You're booked: {service} on {date} at {time} ({duration} min). Reference {reference}. Reply CANCEL if your plans change.",
                    "send_ics": true,
                    "notify_email": ""
                  },
                  "calendar": {
                    "provider": "google",
                    "write_calendar_id": "primary",
                    "busy_calendar_ids": [],
                    "event_title": "{service} - {name}",
                    "event_description": "Booked on WhatsApp.\nPhone: +{phone}\nReference: {reference}\n{notes}"
                  },
                  "providers": []
                },
                "flow": {
                  "key": "booking",
                  "name": "Appointment booking",
                  "kind": "booking",
                  "enabled": true,
                  "is_default": true,
                  "trigger_keywords": [],
                  "id": "1234567890123456",
                  "status": "published",
                  "can_send": true,
                  "health": "AVAILABLE",
                  "last_published_at": "2026-11-06T00:00:00Z",
                  "updated_at": "2026-11-06T00:00:00.000Z"
                },
                "flows": [
                  {
                    "key": "booking",
                    "name": "Appointment booking",
                    "kind": "booking",
                    "enabled": true,
                    "is_default": true,
                    "trigger_keywords": [],
                    "id": "1234567890123456",
                    "status": "published",
                    "can_send": true,
                    "health": "AVAILABLE",
                    "last_published_at": "2026-11-06T00:00:00Z",
                    "updated_at": "2026-11-06T00:00:00.000Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/{key}/send": {
      "post": {
        "tags": [
          "Book-and-Pay"
        ],
        "operationId": "sendFlow",
        "summary": "Send a Flow to a contact (the booking form or another form)",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. A Flow of the number's Book-and-Pay section, by its `key` (GET /flows). A Flow message is free-form: it can only go to a contact who wrote to the number in the last 24 hours (422 `outside_24h_window`; send an approved template first, then the Flow when they answer). The Flow must be enabled and published (409 `flow_not_published`). The contact's answers come back as `booking.created` (a booking Flow) or `flow.completed` (a form Flow). Counts as one message of the plan.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The Flow's key (GET /flows).",
            "type": "string",
            "x-example": "booking"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/FlowSendRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent.",
            "schema": {
              "$ref": "#/definitions/FlowSendResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f7rhb",
                "sent": true,
                "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBI...",
                "session_id": 518,
                "flow": {
                  "key": "booking",
                  "name": "Appointment booking",
                  "kind": "booking"
                },
                "contact": "61412345678",
                "purpose": "book",
                "note": "Sent. The contact's answers come back as the booking.created event (a booking Flow) or the flow.completed event (a form Flow)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/calendar": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "getCalendar",
        "summary": "Everything on the calendar for a range of days",
        "description": "Scope: `bookings:manage` (or `messages:read`). One feed for a range of days (business time zone; default 7 days from today, at most 62): the appointments, the blocked time, the busy time of the connected calendar (our own appointments left out) and the times held right now, each with `start`/`end` in UTC and `start_local`/`end_local`; plus the opening hours per day (overrides applied), the staff and the services. `include` picks any of `bookings,blocks,busy,holds`; cancelled appointments only with `cancelled=true`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "The first day, YYYY-MM-DD in the business time zone. Default today.",
            "type": "string",
            "x-example": "2026-11-10"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "The last day (included). Default from + 6 days; at most 62 days.",
            "type": "string",
            "x-example": "2026-11-16"
          },
          {
            "name": "provider_id",
            "in": "query",
            "required": false,
            "description": "Only this staff member's entries (and the business-wide ones). Left out: everyone.",
            "type": "string",
            "x-example": "maria"
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "Comma list of bookings, blocks, busy, holds. Default: all four.",
            "type": "string",
            "x-example": "bookings,blocks"
          },
          {
            "name": "cancelled",
            "in": "query",
            "required": false,
            "description": "true: also the cancelled appointments.",
            "type": "boolean",
            "default": false
          }
        ],
        "responses": {
          "200": {
            "description": "The feed.",
            "schema": {
              "$ref": "#/definitions/CalendarFeed"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c1fd2",
                "timezone": "Australia/Sydney",
                "from": "2026-11-10",
                "to": "2026-11-16",
                "now_local": "2026-11-11T10:42",
                "enabled": true,
                "web": {
                  "enabled": true,
                  "slug": "sample-salon",
                  "url": "https://www.app2email.com/book/sample-salon"
                },
                "hours": {
                  "2026-11-12": [
                    [
                      "09:00",
                      "17:00"
                    ]
                  ],
                  "2026-11-14": []
                },
                "providers": [
                  {
                    "id": "maria",
                    "name": "Maria",
                    "enabled": true,
                    "services": [
                      "haircut"
                    ],
                    "hours": {
                      "2026-11-12": [
                        [
                          "09:00",
                          "17:00"
                        ]
                      ]
                    }
                  }
                ],
                "services": [
                  {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30,
                    "price": "$40",
                    "description": "",
                    "enabled": true
                  }
                ],
                "events": [
                  {
                    "kind": "booking",
                    "id": 42,
                    "reference": "BK-7Q3M2A",
                    "status": "confirmed",
                    "start": "2026-11-11T23:00:00.000Z",
                    "end": "2026-11-11T23:30:00.000Z",
                    "start_local": "2026-11-12T10:00",
                    "end_local": "2026-11-12T10:30",
                    "service_id": "haircut",
                    "service_name": "Haircut",
                    "duration_min": 30,
                    "provider_id": "maria",
                    "provider_name": "Maria",
                    "contact": "61412345678",
                    "contact_name": "John Smith",
                    "notes_count": 1
                  },
                  {
                    "id": 3,
                    "provider_id": "maria",
                    "title": "Lunch",
                    "notes": "",
                    "start": "2026-11-14T01:00:00.000Z",
                    "end": "2026-11-14T02:00:00.000Z",
                    "start_local": "2026-11-14T12:00",
                    "end_local": "2026-11-14T13:00",
                    "source": "api",
                    "created_by": "API key Planner",
                    "created": "2026-11-11T01:12:09.000Z",
                    "updated": "2026-11-11T01:12:09.000Z",
                    "kind": "block"
                  },
                  {
                    "kind": "busy",
                    "provider_id": "maria",
                    "title": "Busy (Google Calendar)",
                    "start": "2026-11-12T03:00:00.000Z",
                    "end": "2026-11-12T04:00:00.000Z",
                    "start_local": "2026-11-12T14:00",
                    "end_local": "2026-11-12T15:00"
                  },
                  {
                    "kind": "hold",
                    "reference": "BK-4HT9XC",
                    "service_id": "haircut",
                    "service_name": "Haircut",
                    "provider_id": "maria",
                    "name": "John",
                    "start": "2026-11-12T22:00:00.000Z",
                    "end": "2026-11-12T22:30:00.000Z",
                    "start_local": "2026-11-13T09:00",
                    "end_local": "2026-11-13T09:30",
                    "expires": "2026-11-11T01:22:00.000Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/calendar/blocks": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listCalendarBlocks",
        "summary": "The blocked times",
        "description": "Scope: `bookings:manage` (or `messages:read`). The time blocks touching a range of days (business time zone; default 31 days from today, at most 62), soonest first. With `provider_id`: that staff member's blocks and the business-wide ones.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "The first day, YYYY-MM-DD. Default today.",
            "type": "string",
            "x-example": "2026-11-10"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "The last day (included). Default from + 30 days.",
            "type": "string",
            "x-example": "2026-12-10"
          },
          {
            "name": "provider_id",
            "in": "query",
            "required": false,
            "description": "One staff member's blocks and the business-wide ones.",
            "type": "string",
            "x-example": "maria"
          }
        ],
        "responses": {
          "200": {
            "description": "The blocks.",
            "schema": {
              "$ref": "#/definitions/BlocksResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c2bl3",
                "blocks": [
                  {
                    "id": 3,
                    "provider_id": "maria",
                    "title": "Lunch",
                    "notes": "",
                    "start": "2026-11-14T01:00:00.000Z",
                    "end": "2026-11-14T02:00:00.000Z",
                    "start_local": "2026-11-14T12:00",
                    "end_local": "2026-11-14T13:00",
                    "source": "api",
                    "created_by": "API key Planner",
                    "created": "2026-11-11T01:12:09.000Z",
                    "updated": "2026-11-11T01:12:09.000Z"
                  }
                ],
                "count": 1,
                "from": "2026-11-10",
                "to": "2026-12-10",
                "timezone": "Australia/Sydney"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "createCalendarBlock",
        "summary": "Block time so that no one can book it",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Time off, a break, a closed afternoon: for one staff member (`provider_id`) or the whole business. Give `start` and `end`, or `date` for one whole day. Existing appointments are not touched. The block is made with `source` \"api\" and `created_by` \"API key <name>\"; `calendar.block.created` is sent. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BlockCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Blocked.",
            "schema": {
              "$ref": "#/definitions/BlockResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c3bk4",
                "block": {
                  "id": 3,
                  "provider_id": "maria",
                  "title": "Lunch",
                  "notes": "",
                  "start": "2026-11-14T01:00:00.000Z",
                  "end": "2026-11-14T02:00:00.000Z",
                  "start_local": "2026-11-14T12:00",
                  "end_local": "2026-11-14T13:00",
                  "source": "api",
                  "created_by": "API key Planner",
                  "created": "2026-11-11T01:12:09.000Z",
                  "updated": "2026-11-11T01:12:09.000Z"
                },
                "note": "Blocked. No one can book that time."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/calendar/blocks/{id}": {
      "patch": {
        "tags": [
          "Calendar"
        ],
        "operationId": "updateCalendarBlock",
        "summary": "Change a blocked time",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Any of `start`, `end`, `date`, `provider_id`, `title`, `notes`; what is left out stays.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The block's id.",
            "type": "string",
            "x-example": "3"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BlockUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/BlockResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4bu5",
                "block": {
                  "id": 3,
                  "provider_id": "maria",
                  "title": "Long lunch",
                  "notes": "",
                  "start": "2026-11-14T01:00:00.000Z",
                  "end": "2026-11-14T02:30:00.000Z",
                  "start_local": "2026-11-14T12:00",
                  "end_local": "2026-11-14T13:30",
                  "source": "api",
                  "created_by": "API key Planner",
                  "created": "2026-11-11T01:12:09.000Z",
                  "updated": "2026-11-11T01:12:09.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Calendar"
        ],
        "operationId": "deleteCalendarBlock",
        "summary": "Remove a blocked time",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The time can be booked again. `calendar.block.deleted` is sent.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The block's id.",
            "type": "string",
            "x-example": "3"
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "schema": {
              "$ref": "#/definitions/BlockDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c5bd6",
                "deleted": true,
                "block": {
                  "id": 3,
                  "provider_id": "maria",
                  "title": "Lunch",
                  "notes": "",
                  "start": "2026-11-14T01:00:00.000Z",
                  "end": "2026-11-14T02:00:00.000Z",
                  "start_local": "2026-11-14T12:00",
                  "end_local": "2026-11-14T13:00",
                  "source": "api",
                  "created_by": "API key Planner",
                  "created": "2026-11-11T01:12:09.000Z",
                  "updated": "2026-11-11T01:12:09.000Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/services": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listBookableServices",
        "summary": "The services a customer can book, and their staff",
        "description": "Scope: `bookings:manage` (or `messages:read`). The enabled services with their length, price and description, and the staff members who do each one (`staff` is empty when the business has no staff). The ids go into GET /bookings/availability, GET /bookings/next, POST /bookings and POST /bookings/holds.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The services.",
            "schema": {
              "$ref": "#/definitions/BookableServicesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c6sv7",
                "services": [
                  {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30,
                    "price": "$40",
                    "description": null,
                    "staff": [
                      "maria",
                      "tom"
                    ]
                  }
                ],
                "timezone": "Australia/Sydney",
                "enabled": true
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/staff": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listBookingStaff",
        "summary": "The staff members and the services they do",
        "description": "Scope: `bookings:manage` (or `messages:read`). The enabled staff members (`provider_id` in the other calls) with the ids of the enabled services each one does. Empty when the business has no staff.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The staff.",
            "schema": {
              "$ref": "#/definitions/StaffResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c7st8",
                "staff": [
                  {
                    "id": "maria",
                    "name": "Maria",
                    "services": [
                      "haircut",
                      "colour"
                    ]
                  }
                ],
                "timezone": "Australia/Sydney",
                "enabled": true
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/next": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "getNextBookingSlots",
        "summary": "The next free start times for a service, across days",
        "description": "Scope: `bookings:manage` (or `messages:read`). Like GET /bookings/availability but without choosing days: the next `count` free start times after `after` (default now), looking at most 60 days ahead. Each slot's `id` is what POST /bookings, /bookings/holds and /bookings/{id}/reschedule take as `start`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "service_id",
            "in": "query",
            "required": false,
            "description": "The service (GET /bookings/services).",
            "type": "string",
            "x-example": "haircut"
          },
          {
            "name": "provider_id",
            "in": "query",
            "required": false,
            "description": "One staff member's own availability. Left out: anyone available.",
            "type": "string",
            "x-example": "maria"
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "Only times after this: a day (YYYY-MM-DD, its start in the business time zone) or an ISO 8601 time. Default now.",
            "type": "string",
            "x-example": "2026-11-12"
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "description": "How many slots (1 to 20).",
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 5
          }
        ],
        "responses": {
          "200": {
            "description": "The slots.",
            "schema": {
              "$ref": "#/definitions/NextSlotsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c8nx9",
                "slots": [
                  {
                    "id": "2026-11-12T09:00",
                    "date": "2026-11-12",
                    "title": "9:00 AM",
                    "start": "2026-11-11T22:00:00.000Z",
                    "end": "2026-11-11T22:30:00.000Z",
                    "providers": [
                      "maria"
                    ]
                  }
                ],
                "count": 1,
                "timezone": "Australia/Sydney",
                "enabled": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/{id}/reschedule": {
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "rescheduleBooking",
        "summary": "Move an appointment to another time",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Moves a confirmed appointment in place: same `id` and `reference`, the calendar event moved, reminders start again. `start` must be a free slot (the booking's own time counts as free). The customer is told on WhatsApp unless `notify` is false. `booking.rescheduled` is sent with `rescheduled_from`. 409 `booking_slot_taken` when the time is not free. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingRescheduleRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Moved.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c0rs2",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "confirmed",
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "contact_email": "john@example.com",
                  "service": {
                    "id": "haircut",
                    "name": "Haircut",
                    "duration_min": 30
                  },
                  "start": "2026-11-11T23:00:00.000Z",
                  "end": "2026-11-11T23:30:00.000Z",
                  "timezone": "Australia/Sydney",
                  "source": "api",
                  "calendar": {
                    "provider": "google",
                    "event_id": "evt_1a2b3c",
                    "url": null,
                    "error": null
                  },
                  "answers": {},
                  "notes": "First visit",
                  "provider": {
                    "id": "maria",
                    "name": "Maria"
                  },
                  "credits_used": 0,
                  "link_id": null,
                  "notes_count": 1,
                  "created": "2026-11-06T01:12:09.000Z"
                },
                "note": "Moved. The booking keeps its id and reference. The customer is told on WhatsApp."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/{id}/notes": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listBookingNotes",
        "summary": "The internal notes of an appointment and its customer",
        "description": "Scope: `bookings:manage` (or `messages:read`). The notes written on this appointment and the customer's other notes, pinned first then newest; `on_this_booking` tells them apart. Notes are never shown to the customer.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          }
        ],
        "responses": {
          "200": {
            "description": "The notes.",
            "schema": {
              "$ref": "#/definitions/NotesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d1nl3",
                "notes": [
                  {
                    "id": 7,
                    "contact": "61412345678",
                    "appointment_id": 42,
                    "booking_reference": "BK-7Q3M2A",
                    "body": "Prefers the window seat.",
                    "author": "API key Planner",
                    "author_kind": "api",
                    "pinned": false,
                    "created": "2026-11-11T01:12:09.000Z",
                    "updated": "2026-11-11T01:12:09.000Z",
                    "on_this_booking": true
                  }
                ],
                "count": 1,
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A"
                },
                "contact": "61412345678"
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "addBookingNote",
        "summary": "Add an internal note to an appointment",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The note is about the appointment's customer and written on this appointment. `author` is \"API key <name>\" and `author_kind` \"api\". `booking.note.created` is sent. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/NoteCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Added.",
            "schema": {
              "$ref": "#/definitions/NoteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d2na4",
                "note": {
                  "id": 7,
                  "contact": "61412345678",
                  "appointment_id": 42,
                  "booking_reference": "BK-7Q3M2A",
                  "body": "Prefers the window seat.",
                  "author": "API key Planner",
                  "author_kind": "api",
                  "pinned": false,
                  "created": "2026-11-11T01:12:09.000Z",
                  "updated": "2026-11-11T01:12:09.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/notes": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listCustomerNotes",
        "summary": "The internal notes of a customer",
        "description": "Scope: `bookings:manage` (or `messages:read`). Every note about one customer (`contact` is required), pinned first then newest. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "The customer: number with country code, or business-scoped user id. Required.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The notes.",
            "schema": {
              "$ref": "#/definitions/NotesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d3nc5",
                "notes": [
                  {
                    "id": 7,
                    "contact": "61412345678",
                    "appointment_id": 42,
                    "booking_reference": "BK-7Q3M2A",
                    "body": "Prefers the window seat.",
                    "author": "API key Planner",
                    "author_kind": "api",
                    "pinned": false,
                    "created": "2026-11-11T01:12:09.000Z",
                    "updated": "2026-11-11T01:12:09.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1,
                "contact": "61412345678"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "addCustomerNote",
        "summary": "Add an internal note to a customer",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Give `contact`, or `booking_id` to write it on one appointment (the customer is taken from it). `author` is \"API key <name>\", `author_kind` \"api\". `booking.note.created` is sent. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/NoteCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Added.",
            "schema": {
              "$ref": "#/definitions/NoteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d4nn6",
                "note": {
                  "id": 7,
                  "contact": "61412345678",
                  "appointment_id": 42,
                  "booking_reference": "BK-7Q3M2A",
                  "body": "Prefers the window seat.",
                  "author": "API key Planner",
                  "author_kind": "api",
                  "pinned": false,
                  "created": "2026-11-11T01:12:09.000Z",
                  "updated": "2026-11-11T01:12:09.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/notes/{note_id}": {
      "delete": {
        "tags": [
          "Calendar"
        ],
        "operationId": "deleteBookingNote",
        "summary": "Delete an internal note",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The note is hidden from every list.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "note_id",
            "in": "path",
            "required": true,
            "description": "The note's id.",
            "type": "string",
            "x-example": "7"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/NoteDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d5nd7",
                "deleted": true,
                "id": 7
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/links": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listBookingLinks",
        "summary": "The personal booking links",
        "description": "Scope: `bookings:manage` (or `messages:read`). The personal links of the number, newest first; `contact` shows one customer's. Each has its `state` (ok, expired, revoked, used_up, off) and how often it was opened. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "Only this customer's links.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The links.",
            "schema": {
              "$ref": "#/definitions/BookingLinksResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "e1ll8",
                "links": [
                  {
                    "id": 21,
                    "code": "k3XbQ9rTzP2m",
                    "url": "https://www.app2email.com/book/k3XbQ9rTzP2m",
                    "kind": "personal",
                    "contact": "61412345678",
                    "contact_name": "John",
                    "service_id": null,
                    "provider_id": null,
                    "purpose": "book",
                    "booking_id": null,
                    "single_use": false,
                    "max_uses": 0,
                    "uses": 0,
                    "expires": "2026-11-18T01:12:09.000Z",
                    "revoked": null,
                    "source": "api",
                    "created_by": "API key Planner",
                    "open_count": 0,
                    "last_opened": null,
                    "created": "2026-11-11T01:12:09.000Z",
                    "state": "ok"
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "createBookingLink",
        "summary": "Make a link that opens the online booking page",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. A link for a customer to book, move an appointment (`purpose` reschedule + `booking_id`) or manage their appointments (`purpose` manage). Send the `url` to the customer yourself. With a `contact` the page knows the customer and confirms the booking right away; without one it is a one-off link and the customer confirms on WhatsApp. The online booking page must be switched on, else the answer says the link will not open yet. `created_by` is \"API key <name>\", `source` \"api\". Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingLinkRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/BookingLinkResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "e2lc9",
                "link": {
                  "id": 21,
                  "code": "k3XbQ9rTzP2m",
                  "url": "https://www.app2email.com/book/k3XbQ9rTzP2m",
                  "kind": "personal",
                  "contact": "61412345678",
                  "contact_name": "John",
                  "service_id": null,
                  "provider_id": null,
                  "purpose": "book",
                  "booking_id": null,
                  "single_use": false,
                  "max_uses": 0,
                  "uses": 0,
                  "expires": "2026-11-18T01:12:09.000Z",
                  "revoked": null,
                  "source": "api",
                  "created_by": "API key Planner",
                  "open_count": 0,
                  "last_opened": null,
                  "created": "2026-11-11T01:12:09.000Z",
                  "state": "ok"
                },
                "note": "Send the url to the customer. It opens the booking page for them."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/links/{code}": {
      "delete": {
        "tags": [
          "Calendar"
        ],
        "operationId": "revokeBookingLink",
        "summary": "Revoke a personal booking link",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The link stops opening. The public address is not a personal link: change it on the dashboard.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The link's code (or its id).",
            "type": "string",
            "x-example": "k3XbQ9rTzP2m"
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked.",
            "schema": {
              "$ref": "#/definitions/BookingLinkResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "e3lr1",
                "link": {
                  "id": 21,
                  "code": "k3XbQ9rTzP2m",
                  "url": "https://www.app2email.com/book/k3XbQ9rTzP2m",
                  "kind": "personal",
                  "contact": "61412345678",
                  "contact_name": "John",
                  "service_id": null,
                  "provider_id": null,
                  "purpose": "book",
                  "booking_id": null,
                  "single_use": false,
                  "max_uses": 0,
                  "uses": 0,
                  "expires": "2026-11-18T01:12:09.000Z",
                  "revoked": "2026-11-11T02:00:00.000Z",
                  "source": "api",
                  "created_by": "API key Planner",
                  "open_count": 0,
                  "last_opened": null,
                  "created": "2026-11-11T01:12:09.000Z",
                  "state": "revoked"
                },
                "note": "Revoked. The link no longer opens."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/holds": {
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "createBookingHold",
        "summary": "Keep a free time for a few minutes",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Keeps a free time for `minutes` (1 to 30, default 10) so no one else can book it while the customer decides: it counts as taken in the availability, the calendar and every booking check. The slot is checked like a booking is; 409 `booking_slot_taken` when it is not free. Book it with POST /bookings and `hold` (the `reference`), or release it with DELETE; it frees itself at `expires`. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/HoldRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Held.",
            "schema": {
              "$ref": "#/definitions/HoldResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1hc2",
                "hold": {
                  "reference": "BK-4HT9XC",
                  "status": "held",
                  "service_id": "haircut",
                  "provider_id": "maria",
                  "contact": "61412345678",
                  "name": "John",
                  "start": "2026-11-09T22:00:00.000Z",
                  "end": "2026-11-09T22:30:00.000Z",
                  "start_local": "2026-11-10T09:00",
                  "end_local": "2026-11-10T09:30",
                  "expires": "2026-11-09T04:10:00.000Z",
                  "source": "api"
                },
                "note": "The time is kept until hold.expires: nobody else can book it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/holds/{reference}": {
      "delete": {
        "tags": [
          "Calendar"
        ],
        "operationId": "releaseBookingHold",
        "summary": "Release a held time",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Frees the time at once. Releasing a time that was already released answers 200 again; one that expired or was booked answers 409 `hold_expired`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "description": "The hold's reference, as POST /bookings/holds answered.",
            "type": "string",
            "x-example": "BK-4HT9XC"
          }
        ],
        "responses": {
          "200": {
            "description": "Released.",
            "schema": {
              "$ref": "#/definitions/HoldReleaseResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f2hr3",
                "released": true,
                "hold": {
                  "reference": "BK-4HT9XC",
                  "status": "released",
                  "service_id": "haircut",
                  "provider_id": "maria",
                  "contact": "61412345678",
                  "name": "John",
                  "start": "2026-11-09T22:00:00.000Z",
                  "end": "2026-11-09T22:30:00.000Z",
                  "start_local": "2026-11-10T09:00",
                  "end_local": "2026-11-10T09:30",
                  "expires": "2026-11-09T04:10:00.000Z",
                  "source": "api"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/calling/settings": {
      "get": {
        "tags": [
          "Calling"
        ],
        "operationId": "getCallSettings",
        "summary": "WhatsApp calling settings",
        "description": "Meta's settings of the number: calling on or off, call icon, call hours, call-back permission, SIP.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "include_sip_credentials",
            "in": "query",
            "required": false,
            "description": "true: the SIP password too (never for a sandbox key).",
            "type": "boolean"
          }
        ],
        "responses": {
          "200": {
            "description": "The settings.",
            "schema": {
              "$ref": "#/definitions/CallSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c1g2s",
                "settings": {
                  "calling": {
                    "status": "ENABLED",
                    "call_icon_visibility": "DEFAULT",
                    "callback_permission_status": "ENABLED",
                    "call_hours": {
                      "status": "ENABLED",
                      "timezone_id": "Europe/Berlin",
                      "weekly_operating_hours": [
                        {
                          "day_of_week": "MONDAY",
                          "open_time": "0900",
                          "close_time": "1700"
                        }
                      ]
                    },
                    "sip": {
                      "status": "DISABLED"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Calling"
        ],
        "operationId": "updateCallSettings",
        "summary": "Change the calling settings",
        "description": "Passed to Meta as {\"calling\": {...}}; status in upper case.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CallSettingsUpdate"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/CallSettingsUpdateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c2h3t",
                "updated": [
                  "status",
                  "call_icon_visibility"
                ],
                "calling": {
                  "status": "ENABLED",
                  "call_icon_visibility": "DEFAULT"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/calls": {
      "post": {
        "tags": [
          "Calling"
        ],
        "operationId": "manageCall",
        "summary": "Start, answer, reject or end a WhatsApp call",
        "description": "Meta's call actions with your SDP. Answer an incoming call within 30 to 60 s. Business-initiated calls need the contact's permission and are billed per minute.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CallRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Taken by WhatsApp.",
            "schema": {
              "$ref": "#/definitions/CallResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c3i4u",
                "action": "accept",
                "call_id": "wacid.HBgLMTY1MDU1NTEyMzQVAgARGCBBQkNERUY"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/calls/permissions/{contact}": {
      "get": {
        "tags": [
          "Calling"
        ],
        "operationId": "getCallPermission",
        "summary": "May the number call this contact",
        "description": "The contact's call permission and how many calls or permission requests are left.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "description": "The contact's number with country code, digits only, or their business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "The permission.",
            "schema": {
              "$ref": "#/definitions/CallPermissionResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4j5v",
                "contact": "61412345678",
                "permission": {
                  "status": "temporary",
                  "expires_at": "2026-11-13T01:00:00.000Z"
                },
                "actions": [
                  {
                    "action_name": "start_call",
                    "can_perform_action": true,
                    "limits": [
                      {
                        "time_period": "PT24H",
                        "max_allowed": 100,
                        "current_usage": 2
                      }
                    ]
                  },
                  {
                    "action_name": "send_call_permission_request",
                    "can_perform_action": false,
                    "limits": [
                      {
                        "time_period": "P1D",
                        "max_allowed": 1,
                        "current_usage": 1,
                        "limit_expiration_time": 1794013200
                      }
                    ]
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listEvents",
        "summary": "Fetch events (no webhook address needed)",
        "description": "The number's events, fetched instead of pushed: for an agent or a script with no public address for a webhook. Every event is the JSON a webhook gets (https://www.app2email.com/docs/api/webhooks), with the same id, oldest first. Keep the `cursor` of each answer and pass it as `after` on the next call; after a lost answer the same event can come again, so skip ids you have handled. `wait` holds the answer until an event arrives (long polling; one waiting call at a time is enough). The first call switches the number's feed on: events are kept from then on, for 72 hours (the newest 2,000), and the feed switches itself off after 7 days without a call. Webhooks keep working beside it.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "The `cursor` of the previous answer, unchanged. Left out: from the oldest event still kept. `now`: only events from this moment on.",
            "type": "string",
            "x-example": "ec_184467"
          },
          {
            "name": "wait",
            "in": "query",
            "required": false,
            "description": "Seconds to wait for an event when there is none yet (0 to 25). 0, the default, answers at once.",
            "type": "integer",
            "minimum": 0,
            "maximum": 25,
            "default": 0
          },
          {
            "name": "types",
            "in": "query",
            "required": false,
            "description": "Only these event types, comma separated. Left out: every event.",
            "type": "string",
            "x-example": "message.received,message.status"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Only events of this contact (data.from, data.to, data.contact or data.number): full number, digits, with country code.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          }
        ],
        "responses": {
          "200": {
            "description": "The events after the cursor (an empty list when there are none).",
            "schema": {
              "$ref": "#/definitions/EventFeedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "e7fd2",
                "events": [
                  {
                    "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                    "type": "message.status",
                    "created": "2026-11-15T03:10:02.000Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
                      "to": "61412345678",
                      "status": "delivered",
                      "timestamp": "2026-11-15T03:10:01.000Z",
                      "sent_by": "api"
                    }
                  },
                  {
                    "id": "evt_Ab7c2d9Ef4Gh6Jk8Lm03",
                    "type": "message.received",
                    "created": "2026-11-15T03:10:09.000Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
                      "from": "61412345678",
                      "name": "John",
                      "type": "text",
                      "text": "Thanks! When will it arrive?",
                      "timestamp": "2026-11-15T03:10:08.000Z"
                    }
                  }
                ],
                "count": 2,
                "cursor": "ec_184467",
                "has_more": false,
                "feed": {
                  "on": true,
                  "started": false,
                  "kept_hours": 72,
                  "waited": true
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows": {
      "get": {
        "tags": [
          "Flows"
        ],
        "operationId": "listFlows",
        "summary": "List WhatsApp Flows",
        "description": "Every flow of the WhatsApp Business Account: id, name, status, categories, validation errors. This number's Book-and-Pay Flows also have `key`, `can_send` and `booking_flow` (POST /flows/{key}/send sends them); the first page adds the Book-and-Pay Flows not uploaded yet (no id). Needs 'messages:read' or 'bookings:manage'.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 100.",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous answer.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The flows.",
            "schema": {
              "$ref": "#/definitions/FlowListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1lst",
                "flows": [
                  {
                    "id": "1234567890123456",
                    "name": "appointment_booking",
                    "status": "DRAFT",
                    "categories": [
                      "APPOINTMENT_BOOKING"
                    ],
                    "validation_errors": []
                  },
                  {
                    "id": "1234567890123457",
                    "name": "feedback",
                    "status": "PUBLISHED",
                    "categories": [
                      "SURVEY"
                    ],
                    "validation_errors": []
                  },
                  {
                    "id": "1234567890123458",
                    "name": "Appointment booking - +61 2 9876 5432",
                    "status": "PUBLISHED",
                    "categories": [
                      "APPOINTMENT_BOOKING"
                    ],
                    "validation_errors": [],
                    "key": "booking",
                    "can_send": true,
                    "booking_flow": {
                      "key": "booking",
                      "name": "Appointment booking",
                      "kind": "booking",
                      "enabled": true,
                      "is_default": true,
                      "trigger_keywords": [],
                      "id": "1234567890123458",
                      "status": "published",
                      "can_send": true,
                      "health": "AVAILABLE",
                      "last_published_at": "2026-11-06T00:00:00Z",
                      "updated_at": "2026-11-06T00:00:00.000Z"
                    }
                  }
                ],
                "next_cursor": null,
                "count": 3,
                "enabled": true,
                "note": "A Flow with a key is one of this number's Book-and-Pay Flows: POST /v1/{number}/flows/{key}/send sends it to a contact inside their 24 hour window (can_send), and its trigger words send it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Flows"
        ],
        "operationId": "createFlow",
        "summary": "Create a flow (draft, or published at once)",
        "description": "Needs 'templates:manage'. A draft; with flow_json and publish: true it is published at once (cannot be undone). WABA-wide: every number on this WhatsApp Business Account shares its flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/FlowCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created (validation_errors: what to fix before publishing).",
            "schema": {
              "$ref": "#/definitions/FlowCreateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1new",
                "flow": {
                  "id": "1234567890123456",
                  "name": "appointment_booking",
                  "status": "DRAFT"
                },
                "validation_errors": [],
                "note": "The flow belongs to the whole WhatsApp Business Account: every number on it can send it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/{id}": {
      "get": {
        "tags": [
          "Flows"
        ],
        "operationId": "getFlow",
        "summary": "One flow: status, validation errors, health",
        "description": "Status, categories, validation errors, Flow JSON version, endpoint, and whether it can be sent (health_status).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "The flow.",
            "schema": {
              "$ref": "#/definitions/FlowDetailResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1get",
                "flow": {
                  "id": "1234567890123456",
                  "name": "appointment_booking",
                  "status": "DRAFT",
                  "categories": [
                    "APPOINTMENT_BOOKING"
                  ],
                  "validation_errors": [],
                  "json_version": "7.2",
                  "health_status": {
                    "can_send_message": "AVAILABLE",
                    "entities": [
                      {
                        "entity_type": "FLOW",
                        "id": "1234567890123456",
                        "can_send_message": "AVAILABLE"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Flows"
        ],
        "operationId": "updateFlow",
        "summary": "Change a flow's name, categories or endpoint",
        "description": "Needs 'templates:manage'. The Flow JSON: PUT /flows/{id}/json. A published flow goes back to DRAFT until you publish it again; messages already sent keep the old version. WABA-wide: every number on this WhatsApp Business Account shares its flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/FlowUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/FlowUpdateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1upd",
                "flow_id": "1234567890123456",
                "changed": [
                  "name"
                ],
                "note": "The flow was PUBLISHED: it is a DRAFT again until you publish it (POST /flows/1234567890123456/publish); messages already sent keep the old version."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Flows"
        ],
        "operationId": "deleteFlow",
        "summary": "Delete a draft flow",
        "description": "Needs 'templates:manage'. Drafts only; deprecate a published flow instead. WABA-wide: every number on this WhatsApp Business Account shares its flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/FlowDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1del",
                "deleted": "1234567890123456",
                "name": "appointment_booking"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/{id}/json": {
      "get": {
        "tags": [
          "Flows"
        ],
        "operationId": "getFlowJson",
        "summary": "A flow's Flow JSON",
        "description": "The flow.json WhatsApp keeps for the flow.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "The Flow JSON.",
            "schema": {
              "$ref": "#/definitions/FlowJsonResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1jsn",
                "flow_id": "1234567890123456",
                "flow_json": {
                  "version": "7.2",
                  "screens": [
                    {
                      "id": "WELCOME",
                      "title": "Welcome",
                      "terminal": true,
                      "success": true,
                      "data": {},
                      "layout": {
                        "type": "SingleColumnLayout",
                        "children": [
                          {
                            "type": "TextHeading",
                            "text": "Book a visit"
                          },
                          {
                            "type": "Footer",
                            "label": "Done",
                            "on-click-action": {
                              "name": "complete",
                              "payload": {}
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Flows"
        ],
        "operationId": "updateFlowJson",
        "summary": "Replace a flow's Flow JSON",
        "description": "Needs 'templates:manage'. The body is the Flow JSON (or {\"flow_json\": {...}}), max 10 MB; the answer lists WhatsApp's validation errors. A published flow goes back to DRAFT until you publish it again; messages already sent keep the old version. WABA-wide: every number on this WhatsApp Business Account shares its flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Taken (check validation_errors).",
            "schema": {
              "$ref": "#/definitions/FlowJsonUploadResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1put",
                "flow_id": "1234567890123456",
                "validation_errors": [],
                "note": "WhatsApp found no errors. Publish with POST /flows/1234567890123456/publish (cannot be undone)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/{id}/publish": {
      "post": {
        "tags": [
          "Flows"
        ],
        "operationId": "publishFlow",
        "summary": "Publish a flow (cannot be undone)",
        "description": "Needs 'templates:manage'. A draft without validation errors. Afterwards it cannot be deleted (deprecate it instead); a change puts it back to DRAFT until published again. WABA-wide: every number on this WhatsApp Business Account shares its flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "Published.",
            "schema": {
              "$ref": "#/definitions/FlowStateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1pub",
                "flow_id": "1234567890123456",
                "name": "appointment_booking",
                "previous_status": "DRAFT",
                "status": "PUBLISHED",
                "note": "Published for every number on this WhatsApp Business Account. It cannot be deleted (deprecate it instead). Changing its name, categories, endpoint or Flow JSON puts it back to DRAFT until you publish again; messages already sent keep the old version."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/{id}/deprecate": {
      "post": {
        "tags": [
          "Flows"
        ],
        "operationId": "deprecateFlow",
        "summary": "Deprecate a published flow (cannot be undone)",
        "description": "Needs 'templates:manage'. It can no longer be sent or opened. WABA-wide: every number on this WhatsApp Business Account shares its flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "Deprecated.",
            "schema": {
              "$ref": "#/definitions/FlowStateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1dep",
                "flow_id": "1234567890123456",
                "name": "appointment_booking",
                "previous_status": "PUBLISHED",
                "status": "DEPRECATED",
                "note": "Deprecated: it can no longer be sent or opened, on every number of this WhatsApp Business Account. This cannot be undone."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/{id}/preview": {
      "get": {
        "tags": [
          "Flows"
        ],
        "operationId": "getFlowPreview",
        "summary": "A public preview link of a flow (30 days)",
        "description": "Anyone with the link can open it, also in an iframe. A new link: POST.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "The link.",
            "schema": {
              "$ref": "#/definitions/FlowPreviewResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1prv",
                "flow_id": "1234567890123456",
                "preview_url": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=b9d6a1c2",
                "expires_at": "2026-12-06T01:00:00+0000",
                "note": "Anyone with the link can see the flow until it expires (30 days). Add &interactive=true to try it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Flows"
        ],
        "operationId": "renewFlowPreview",
        "summary": "A new preview link of a flow (the old one stops working)",
        "description": "Needs 'templates:manage'. Meta's preview.invalidate(true): the old link stops working at once.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The flow's id (digits).",
            "type": "string",
            "x-example": "1234567890123456"
          }
        ],
        "responses": {
          "200": {
            "description": "The new link.",
            "schema": {
              "$ref": "#/definitions/FlowPreviewResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1prn",
                "flow_id": "1234567890123456",
                "preview_url": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=e4f7c3a9",
                "expires_at": "2026-12-06T01:00:00+0000",
                "note": "A new link; the old one no longer works. Anyone with the link can see the flow until it expires (30 days). Add &interactive=true to try it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/flows/encryption-key": {
      "get": {
        "tags": [
          "Flows"
        ],
        "operationId": "getFlowEncryptionKey",
        "summary": "The number's public key for flows with a data endpoint",
        "description": "This number only (each number has its own key). signature_status MISMATCH: set the key again. set_by: bookings when it is the key Book-and-Pay made for its Flows.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The key, or null.",
            "schema": {
              "$ref": "#/definitions/FlowEncryptionKeyResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f2key",
                "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx...\n-----END PUBLIC KEY-----",
                "signature_status": "VALID",
                "set_by": "other",
                "note": "This number's key (each number has its own)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Flows"
        ],
        "operationId": "setFlowEncryptionKey",
        "summary": "Set the number's public key for flow endpoints",
        "description": "Needs 'templates:manage'. A 2048-bit RSA public key, PEM; a private key is refused unsent. This number only. 409 `encryption_key_managed` while Book-and-Pay has its key for the number (one key per number at WhatsApp).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/FlowEncryptionKeyRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Set.",
            "schema": {
              "$ref": "#/definitions/FlowEncryptionKeySetResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f2set",
                "note": "Set for this number only (each number of the WhatsApp Business Account has its own). Your endpoint decrypts with the private key."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/messages/read": {
      "post": {
        "tags": [
          "Messages"
        ],
        "operationId": "markMessageRead",
        "summary": "Mark a received message as read, optionally typing",
        "description": "Blue ticks on a message the contact sent (and the earlier ones of the chat), up to 30 days old; `typing` also shows the typing indicator for up to 25 seconds. Free: not counted, no 24 hour window. Meta's own body on POST /messages works too.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MarkReadRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Marked as read.",
            "schema": {
              "$ref": "#/definitions/MarkReadResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "k2rdq",
                "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
                "status": "read",
                "typing_indicator": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/marketing": {
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "getMarketingStatus",
        "summary": "Where marketing templates go: Cloud API or Marketing Messages API",
        "description": "The route setting (messages.marketing_route), the route a marketing template takes now, WhatsApp's onboarding status and the account's Cloud API switch. `?refresh=true` asks WhatsApp now (otherwise up to 1 hour old).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "refresh",
            "in": "query",
            "required": false,
            "description": "true: ask WhatsApp now.",
            "type": "boolean"
          }
        ],
        "responses": {
          "200": {
            "description": "The status.",
            "schema": {
              "$ref": "#/definitions/MarketingStatusResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q8mkt",
                "marketing": {
                  "route": "auto",
                  "effective_route": "mm_api",
                  "onboarding_status": "ONBOARDED",
                  "cloud_api_marketing_disabled": false,
                  "checked_at": "2026-11-06T01:00:00Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/blocked": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "listBlockedUsers",
        "summary": "WhatsApp users this number blocked",
        "description": "WhatsApp's own block list of the number (not the Do Not Call list). Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The blocked users.",
            "schema": {
              "$ref": "#/definitions/BlockedListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "l3blk",
                "blocked": [
                  {
                    "wa_id": "61412345678"
                  },
                  {
                    "wa_id": "61498765432"
                  }
                ],
                "count": 2,
                "next_cursor": "QVFIUkpVTXl4dE9Ed1"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "operationId": "blockUsers",
        "summary": "Block WhatsApp users",
        "description": "They cannot message the number and it cannot message them. Up to 1000 per call; only users who wrote in the last 24 hours.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BlockUsersRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "All blocked.",
            "schema": {
              "$ref": "#/definitions/BlockUsersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "b1lkp",
                "blocked": [
                  {
                    "input": "+61412345678",
                    "wa_id": "61412345678"
                  }
                ]
              }
            }
          },
          "207": {
            "description": "Some blocked, some not (failed).",
            "schema": {
              "$ref": "#/definitions/BlockUsersResponse"
            },
            "examples": {
              "application/json": {
                "success": false,
                "request_id": "b1lkq",
                "blocked": [
                  {
                    "input": "+61412345678",
                    "wa_id": "61412345678"
                  }
                ],
                "failed": [
                  {
                    "input": "AU.13491208655302741918",
                    "error": {
                      "code": "outside_24h_window",
                      "message": "Re-engagement required: User has not messaged in the last 24 hours",
                      "how_to_fix": "WhatsApp says the contact's 24 hour window is closed. ...",
                      "whatsapp_code": 131047
                    }
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Contacts"
        ],
        "operationId": "unblockUsers",
        "summary": "Unblock WhatsApp users",
        "description": "Same body as blocking.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BlockUsersRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "All unblocked.",
            "schema": {
              "$ref": "#/definitions/BlockUsersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u2lkr",
                "unblocked": [
                  {
                    "input": "+61412345678",
                    "wa_id": "61412345678"
                  }
                ]
              }
            }
          },
          "207": {
            "description": "Some unblocked, some not (failed).",
            "schema": {
              "$ref": "#/definitions/BlockUsersResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/contact-book/{bsuid}": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "getContactBookEntry",
        "summary": "Is a phone number on file for a business-scoped user id",
        "description": "WhatsApp's contact book (per business portfolio) keeps the numbers of users the business talked to, so webhooks include them. Never returns the number.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "bsuid",
            "in": "path",
            "required": true,
            "description": "The business-scoped user id (from_user_id of a message.received event), eg US.13491208655302741918. Parent ids (.ENT.) are refused.",
            "type": "string",
            "x-example": "US.13491208655302741918"
          }
        ],
        "responses": {
          "200": {
            "description": "Present or not.",
            "schema": {
              "$ref": "#/definitions/ContactBookResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4bok",
                "bsuid": "US.13491208655302741918",
                "present": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Contacts"
        ],
        "operationId": "deleteContactBookEntry",
        "summary": "Remove a business-scoped user id from the contact book",
        "description": "Later webhooks may then leave the number out (unless the user writes again).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "bsuid",
            "in": "path",
            "required": true,
            "description": "The business-scoped user id (from_user_id of a message.received event), eg US.13491208655302741918. Parent ids (.ENT.) are refused.",
            "type": "string",
            "x-example": "US.13491208655302741918"
          }
        ],
        "responses": {
          "200": {
            "description": "Removed (deleted false: there was no entry).",
            "schema": {
              "$ref": "#/definitions/ContactBookResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c5bod",
                "bsuid": "US.13491208655302741918",
                "deleted": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/health": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getNumberHealth",
        "summary": "Number health: can it send, quality, limit, name status",
        "description": "WhatsApp's health_status and the number's fields (quality, messaging limit, throughput, display name review, account mode). Kept 60 s.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The health.",
            "schema": {
              "$ref": "#/definitions/NumberHealthResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h7q2m",
                "health": {
                  "can_send_message": "AVAILABLE",
                  "entities": [
                    {
                      "entity_type": "PHONE_NUMBER",
                      "id": "106540352242922",
                      "can_send_message": "AVAILABLE"
                    },
                    {
                      "entity_type": "WABA",
                      "id": "102290129340398",
                      "can_send_message": "AVAILABLE"
                    }
                  ],
                  "display_phone_number": "+49 76659 348270",
                  "verified_name": "Lucky Shrub",
                  "quality_rating": "GREEN",
                  "messaging_limit": "TIER_2K",
                  "throughput": "STANDARD",
                  "status": "CONNECTED",
                  "name_status": "APPROVED",
                  "code_verification_status": "VERIFIED",
                  "account_mode": "LIVE",
                  "is_official_business_account": false,
                  "coexistence": false
                },
                "fetched_at": "2026-11-06T01:00:00.000Z"
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/identity-check": {
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setIdentityCheck",
        "summary": "Turn WhatsApp's identity change check on or off",
        "description": "On: webhooks carry identity_key_hash, and a send with recipient_identity_key_hash is only delivered while it matches (else failed, code 137000).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/IdentityCheckRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/IdentityCheckResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "i2k7d",
                "identity_check": {
                  "enabled": true
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/profile": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getBusinessProfile",
        "summary": "The WhatsApp business profile",
        "description": "About, address, description, email, websites, vertical and the photo link, as WhatsApp users see them.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The profile.",
            "schema": {
              "$ref": "#/definitions/BusinessProfileResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p4m1x",
                "profile": {
                  "about": "Plants and flowers, delivered",
                  "address": "1 Garden Lane, Berlin",
                  "description": "Family florist since 1998.",
                  "email": "hello@luckyshrub.example",
                  "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/123_n.jpg",
                  "websites": [
                    "https://luckyshrub.example"
                  ],
                  "vertical": "RETAIL"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Number"
        ],
        "operationId": "updateBusinessProfile",
        "summary": "Change the WhatsApp business profile",
        "description": "Fields left out stay as they are. Meta's own body (with messaging_product, profile_picture_handle) works unchanged.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BusinessProfileUpdate"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/BusinessProfileUpdateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p5n2y",
                "updated": [
                  "about",
                  "websites"
                ],
                "profile": {
                  "about": "Plants and flowers, delivered same day",
                  "websites": [
                    "https://luckyshrub.example",
                    "https://luckyshrub.example/shop"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/profile/photo": {
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setProfilePhoto",
        "summary": "Change the profile photo from a public link",
        "description": "app2email downloads the image (JPG or PNG, up to 5 MB; 640x640 px suggested) and uploads it to WhatsApp.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ProfilePhotoRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/ProfilePhotoResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f8a3c",
                "updated": [
                  "photo"
                ],
                "link": "https://luckyshrub.example/logo.png"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/profile/display-name": {
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setDisplayName",
        "summary": "Submit a new display name for Meta's review",
        "description": "Answer 202. GET /health shows new_name_status. After approval, number.updated (change display_name, next_step reconnect): press Reconnect on the dashboard within 14 days.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/DisplayNameRequest"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Submitted for review.",
            "schema": {
              "$ref": "#/definitions/DisplayNameResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "d1s9w",
                "display_name": {
                  "current": "Lucky Shrub",
                  "requested": "Lucky Shrub Florist",
                  "status": "PENDING_REVIEW"
                },
                "next_step": "wait_for_review",
                "note": "When Meta approves the name, the number.updated event (change display_name, next_step reconnect) is sent: then press Reconnect on the dashboard within 14 days."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/profile/official-business-account": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getOfficialBusinessAccount",
        "summary": "Official Business Account (blue tick) status",
        "description": "The state of the number's Official Business Account request.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The status.",
            "schema": {
              "$ref": "#/definitions/OfficialBusinessAccountResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "o2b5a",
                "official_business_account": {
                  "status": "UNDER_REVIEW",
                  "status_message": "Your request is being reviewed."
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Number"
        ],
        "operationId": "requestOfficialBusinessAccount",
        "summary": "Request an Official Business Account (blue tick)",
        "description": "Answer 202. Meta decides on notability; supporting_links: 5 to 10 articles about the business.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/OfficialBusinessAccountRequest"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Submitted.",
            "schema": {
              "$ref": "#/definitions/OfficialBusinessAccountResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "o3c6b",
                "official_business_account": {
                  "status": "PENDING",
                  "status_message": "Request submitted."
                },
                "tracking_id": "98765432101234"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/profile/india-compliance": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getIndiaCompliance",
        "summary": "India business compliance information",
        "description": "The legal entity, grievance officer and customer care contacts (numbers in India).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The information (null: none).",
            "schema": {
              "$ref": "#/definitions/IndiaComplianceResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c7i1n",
                "india_compliance": {
                  "entity_name": "Lucky Shrub Pvt Ltd",
                  "entity_type": "PRIVATE_COMPANY",
                  "grievance_officer_details": {
                    "name": "A. Rao",
                    "email": "grievance@luckyshrub.example",
                    "mobile_number": "+919812345678"
                  },
                  "customer_care_details": {
                    "email": "care@luckyshrub.example",
                    "landline_number": "+912212345678"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setIndiaCompliance",
        "summary": "Set the India business compliance information",
        "description": "Replaces it. Needed for numbers that message users in India.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/IndiaCompliance"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/IndiaComplianceResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c8j2o",
                "india_compliance": {
                  "entity_name": "Lucky Shrub Pvt Ltd",
                  "entity_type": "PRIVATE_COMPANY",
                  "grievance_officer_details": {
                    "name": "A. Rao",
                    "email": "grievance@luckyshrub.example",
                    "mobile_number": "+919812345678"
                  },
                  "customer_care_details": {
                    "email": "care@luckyshrub.example",
                    "landline_number": "+912212345678"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/username": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getUsername",
        "summary": "The business username",
        "description": "status none: the number has no username.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The username.",
            "schema": {
              "$ref": "#/definitions/UsernameResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u1n4m",
                "username": "luckyshrub",
                "status": "approved"
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setUsername",
        "summary": "Adopt or change the business username",
        "description": "3 to 35 characters of a-z, 0-9, '.', '_', with a letter. At most 2 changes in 14 days (422 username_change_limit).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/UsernameRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Taken by WhatsApp.",
            "schema": {
              "$ref": "#/definitions/UsernameResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u2o5n",
                "username": "luckyshrub",
                "status": "reserved"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Number"
        ],
        "operationId": "deleteUsername",
        "summary": "Remove the business username",
        "description": "Removing does not reset the 14-day change limit.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "schema": {
              "$ref": "#/definitions/UsernameDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u3p6o",
                "deleted": true
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/username/suggestions": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getUsernameSuggestions",
        "summary": "Usernames reserved for the business",
        "description": "Reserved names have a higher chance of approval.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The reserved names.",
            "schema": {
              "$ref": "#/definitions/UsernameSuggestionsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "u4q7p",
                "suggestions": [
                  "luckyshrub",
                  "lucky.shrub"
                ],
                "count": 2
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/conversation-starters": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getConversationStarters",
        "summary": "Ice breakers, commands and welcome message",
        "description": "What WhatsApp users see when they open a chat or type '/'.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The conversation starters.",
            "schema": {
              "$ref": "#/definitions/ConversationStartersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s1t8q",
                "conversation_starters": {
                  "prompts": [
                    "Track my order",
                    "Opening hours"
                  ],
                  "commands": [
                    {
                      "name": "order",
                      "description": "Where is my order?"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setConversationStarters",
        "summary": "Set ice breakers, commands or the welcome message",
        "description": "Replaces the parts given. A tap or a command arrives as a normal text message (forwarded by email as usual).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ConversationStarters"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/ConversationStartersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s2u9r",
                "conversation_starters": {
                  "prompts": [
                    "Track my order",
                    "Opening hours"
                  ],
                  "commands": [
                    {
                      "name": "order",
                      "description": "Where is my order?"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/qr-codes": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "listQrCodes",
        "summary": "QR codes and short links",
        "description": "Up to 2,000 per number. Codes never expire; WhatsApp gives no scan counts.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "image",
            "in": "query",
            "required": false,
            "description": "Also give each code's image link (qr_image_url) in this format.",
            "type": "string",
            "enum": [
              "svg",
              "png"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The codes.",
            "schema": {
              "$ref": "#/definitions/QrCodeListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q1r2s",
                "qr_codes": [
                  {
                    "code": "4O4YGZEG3RIVE1",
                    "prefilled_message": "Hi, I saw your poster",
                    "deep_link_url": "https://wa.me/message/4O4YGZEG3RIVE1",
                    "qr_image_url": "https://scontent.xx.fbcdn.net/m1/v/t6/qr_4O4YGZEG3RIVE1.png"
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Number"
        ],
        "operationId": "createQrCode",
        "summary": "Create a QR code and wa.me short link",
        "description": "The chat opens with prefilled_message (up to 140 characters). Answer 201.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/QrCodeCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/QrCodeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q2s3t",
                "qr_code": {
                  "code": "4O4YGZEG3RIVE1",
                  "prefilled_message": "Hi, I saw your poster",
                  "deep_link_url": "https://wa.me/message/4O4YGZEG3RIVE1",
                  "qr_image_url": "https://scontent.xx.fbcdn.net/m1/v/t6/qr_4O4YGZEG3RIVE1.png"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/qr-codes/{code}": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getQrCode",
        "summary": "One QR code",
        "description": "With ?image=svg or png, its image link too.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The QR code's code (14 characters), as in the list.",
            "type": "string",
            "x-example": "4O4YGZEG3RIVE1"
          },
          {
            "name": "image",
            "in": "query",
            "required": false,
            "description": "Also give each code's image link (qr_image_url) in this format.",
            "type": "string",
            "enum": [
              "svg",
              "png"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The code.",
            "schema": {
              "$ref": "#/definitions/QrCodeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q3t4u",
                "qr_code": {
                  "code": "4O4YGZEG3RIVE1",
                  "prefilled_message": "Hi, I saw your poster",
                  "deep_link_url": "https://wa.me/message/4O4YGZEG3RIVE1",
                  "qr_image_url": "https://scontent.xx.fbcdn.net/m1/v/t6/qr_4O4YGZEG3RIVE1.png"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Number"
        ],
        "operationId": "updateQrCode",
        "summary": "Change a QR code's prefilled message",
        "description": "The code, link and image stay the same.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The QR code's code (14 characters), as in the list.",
            "type": "string",
            "x-example": "4O4YGZEG3RIVE1"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/QrCodeUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/QrCodeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q4u5v",
                "qr_code": {
                  "code": "4O4YGZEG3RIVE1",
                  "prefilled_message": "Hi, I saw your new poster",
                  "deep_link_url": "https://wa.me/message/4O4YGZEG3RIVE1"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Number"
        ],
        "operationId": "deleteQrCode",
        "summary": "Delete a QR code and its short link",
        "description": "Printed codes and shared links stop working.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The QR code's code (14 characters), as in the list.",
            "type": "string",
            "x-example": "4O4YGZEG3RIVE1"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/QrCodeDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q5v6w",
                "deleted": true,
                "code": "4O4YGZEG3RIVE1"
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/commerce": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getCommerceSettings",
        "summary": "Cart and catalog icon on or off",
        "description": "WhatsApp's defaults: cart on, catalog icon hidden.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The settings.",
            "schema": {
              "$ref": "#/definitions/CommerceSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m1c2a",
                "commerce": {
                  "cart_enabled": true,
                  "catalog_visible": false
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "setCommerceSettings",
        "summary": "Turn the cart or the catalog icon on or off",
        "description": "One or both. Meta's is_cart_enabled / is_catalog_visible work too.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CommerceSettings"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved at WhatsApp.",
            "schema": {
              "$ref": "#/definitions/CommerceSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m2d3b",
                "commerce": {
                  "catalog_visible": true
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/catalog": {
      "get": {
        "tags": [
          "Number"
        ],
        "operationId": "getCatalog",
        "summary": "The connected product catalog",
        "description": "Connected to the WhatsApp Business Account, so to every number on it. null: none.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The catalog.",
            "schema": {
              "$ref": "#/definitions/CatalogResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "g1h2i",
                "catalog": {
                  "id": "1043215907766185",
                  "name": "Lucky Shrub plants"
                },
                "connected": true
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Number"
        ],
        "operationId": "connectCatalog",
        "summary": "Connect a product catalog",
        "description": "A catalog from Commerce Manager; the WABA-wide link for product messages.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CatalogRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Connected.",
            "schema": {
              "$ref": "#/definitions/CatalogResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "g2i3j",
                "catalog": {
                  "id": "1043215907766185"
                },
                "connected": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/payments": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "listPayments",
        "summary": "The payments, newest first",
        "description": "Scope: `bookings:manage` (or `messages:read`). The payments of appointments, package purchases and payment requests. Filter by `booking` (id or reference), `contact`, `status` and `kind`. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "booking",
            "in": "query",
            "required": false,
            "description": "Only this appointment's payments (id or BK- reference).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "Only this customer's payments.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only this status.",
            "type": "string",
            "enum": [
              "pending",
              "paid",
              "partly_refunded",
              "refunded",
              "failed",
              "expired",
              "cancelled"
            ]
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only this kind.",
            "type": "string",
            "enum": [
              "booking",
              "request",
              "package",
              "ticket"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The payments.",
            "schema": {
              "$ref": "#/definitions/PaymentsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p1ls2",
                "payments": [
                  {
                    "id": 15,
                    "kind": "booking",
                    "status": "paid",
                    "provider": "stripe",
                    "amount": 40.0,
                    "amount_label": "$40.00",
                    "full_label": "$40.00",
                    "discount_label": "",
                    "coupon_code": "",
                    "currency": "USD",
                    "refunded": 0.0,
                    "refunded_label": "",
                    "description": "Haircut",
                    "contact": "61412345678",
                    "payer_name": "John Smith",
                    "appointment_id": 42,
                    "booking_reference": "BK-7Q3M2A",
                    "package_purchase_id": null,
                    "checkout_url": "",
                    "link_url": "",
                    "last_error": "",
                    "paid": "2026-11-11T01:15:00.000Z",
                    "refunded_at": null,
                    "created": "2026-11-11T01:10:00.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1,
                "currency": "USD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/payments/{id}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "getPayment",
        "summary": "One payment",
        "description": "Scope: `bookings:manage` (or `messages:read`). No provider key or secret is ever in the answer.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The payment's id.",
            "type": "string",
            "x-example": "15"
          }
        ],
        "responses": {
          "200": {
            "description": "The payment.",
            "schema": {
              "$ref": "#/definitions/PaymentResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p2gt3",
                "payment": {
                  "id": 15,
                  "kind": "booking",
                  "status": "paid",
                  "provider": "stripe",
                  "amount": 40.0,
                  "amount_label": "$40.00",
                  "full_label": "$40.00",
                  "discount_label": "",
                  "coupon_code": "",
                  "currency": "USD",
                  "refunded": 0.0,
                  "refunded_label": "",
                  "description": "Haircut",
                  "contact": "61412345678",
                  "payer_name": "John Smith",
                  "appointment_id": 42,
                  "booking_reference": "BK-7Q3M2A",
                  "package_purchase_id": null,
                  "checkout_url": "",
                  "link_url": "",
                  "last_error": "",
                  "paid": "2026-11-11T01:15:00.000Z",
                  "refunded_at": null,
                  "created": "2026-11-11T01:10:00.000Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/payments/links": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "createPaymentLink",
        "summary": "Ask a customer to pay an amount",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Makes a one-off payment request and the page where the customer pays (the business's own Stripe or PayPal). With `send` true and the customer inside their 24 hour window they also get it on WhatsApp with a Pay button; otherwise send the `url` yourself. 409 `payments_not_connected` when no provider is connected. `payment.paid` is sent when it is paid. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PaymentLinkRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/PaymentLinkResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p3lk4",
                "payment": {
                  "id": 15,
                  "kind": "request",
                  "status": "pending",
                  "provider": "stripe",
                  "amount": 40.0,
                  "amount_label": "$40.00",
                  "full_label": "$40.00",
                  "discount_label": "",
                  "coupon_code": "",
                  "currency": "USD",
                  "refunded": 0.0,
                  "refunded_label": "",
                  "description": "Haircut",
                  "contact": "61412345678",
                  "payer_name": "John Smith",
                  "appointment_id": 42,
                  "booking_reference": "BK-7Q3M2A",
                  "package_purchase_id": null,
                  "checkout_url": "",
                  "link_url": "https://www.app2email.com/book/k3XbQ9rTzP2m",
                  "last_error": "",
                  "paid": null,
                  "refunded_at": null,
                  "created": "2026-11-11T01:10:00.000Z"
                },
                "url": "https://www.app2email.com/book/k3XbQ9rTzP2m",
                "sent": true,
                "note": "The customer was sent the pay link on WhatsApp."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/payments/{id}/refund": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "refundPayment",
        "summary": "Refund a payment, in full or a part",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Sends real money back through the business's own provider; it cannot be undone. `amount` is a part in the payment's currency; left out, everything that is left. A full refund of an appointment's payment sets its `payment.status` to refunded. `booking.refunded` is sent. 409 `refund_not_possible`, 502 `payment_provider_error`. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up). For a payment of kind `ticket` use `POST /tickets/orders/{id}/refund` instead: it also ends the tickets.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The payment's id.",
            "type": "string",
            "x-example": "15"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/RefundRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Refunded.",
            "schema": {
              "$ref": "#/definitions/PaymentResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p4rf5",
                "payment": {
                  "id": 15,
                  "kind": "booking",
                  "status": "partly_refunded",
                  "provider": "stripe",
                  "amount": 40.0,
                  "amount_label": "$40.00",
                  "full_label": "$40.00",
                  "discount_label": "",
                  "coupon_code": "",
                  "currency": "USD",
                  "refunded": 10.0,
                  "refunded_label": "$10.00",
                  "description": "Haircut",
                  "contact": "61412345678",
                  "payer_name": "John Smith",
                  "appointment_id": 42,
                  "booking_reference": "BK-7Q3M2A",
                  "package_purchase_id": null,
                  "checkout_url": "",
                  "link_url": "",
                  "last_error": "",
                  "paid": "2026-11-11T01:15:00.000Z",
                  "refunded_at": null,
                  "created": "2026-11-11T01:10:00.000Z"
                },
                "note": "Refunded through the payment provider. booking.refunded is sent."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/{id}/payment": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "setBookingPayment",
        "summary": "Record a payment taken outside app2email",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The business's own record: `paid` (cash, a terminal), `waived` (nothing to pay) or `due` (still expected). Nothing is charged or refunded; online payments are recorded by the provider. The booking's `payment` shows the result.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The booking's id, or its reference (BK-XXXXXX).",
            "type": "string",
            "x-example": "BK-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BookingPaymentStatusRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded.",
            "schema": {
              "$ref": "#/definitions/BookingResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p5bs6",
                "booking": {
                  "id": 42,
                  "reference": "BK-7Q3M2A",
                  "status": "confirmed",
                  "payment": {
                    "status": "paid",
                    "due": 0.0,
                    "paid": 0.0,
                    "currency": "USD"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/packages": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "listPackages",
        "summary": "The prepaid packages on sale",
        "description": "Scope: `bookings:manage` (or `messages:read`). The enabled packages of the business (config.payments.packages) with their price and the services they cover. Customers buy them on the online booking page; POST /bookings/packages/grant gives one without a payment.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The packages.",
            "schema": {
              "$ref": "#/definitions/PackagesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p6pk7",
                "packages": [
                  {
                    "id": "ten-pack",
                    "name": "10 sessions",
                    "description": "",
                    "sessions": 10,
                    "price_amount": 400.0,
                    "price_label": "$400.00",
                    "valid_days": 365,
                    "services": []
                  }
                ],
                "count": 1,
                "currency": "USD"
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/packages/purchases": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "listPackagePurchases",
        "summary": "The packages customers hold",
        "description": "Scope: `bookings:manage` (or `messages:read`). Purchases and grants, newest first. `status=live` = active with sessions left.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "Only this customer's.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "live, or one status.",
            "type": "string",
            "enum": [
              "live",
              "pending",
              "active",
              "used_up",
              "expired",
              "refunded",
              "cancelled"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        ],
        "responses": {
          "200": {
            "description": "The purchases.",
            "schema": {
              "$ref": "#/definitions/PackagePurchasesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p7pp8",
                "purchases": [
                  {
                    "id": 5,
                    "contact": "61412345678",
                    "contact_name": "John Smith",
                    "package_id": "ten-pack",
                    "package_name": "10 sessions",
                    "services": [],
                    "sessions_total": 10,
                    "sessions_used": 2,
                    "sessions_left": 8,
                    "expires": "2027-11-11T01:15:00.000Z",
                    "status": "active",
                    "payment_id": 17,
                    "created": "2026-11-11T01:15:00.000Z"
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/packages/grant": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "grantPackage",
        "summary": "Give a customer a package without a payment",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Makes an active purchase of a package on sale (`sessions` overrides its session count). `package.purchased` is sent with `granted: true`. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PackageGrantRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Granted.",
            "schema": {
              "$ref": "#/definitions/PackageGrantResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p8pg9",
                "purchase": {
                  "id": 5,
                  "contact": "61412345678",
                  "contact_name": "John Smith",
                  "package_id": "ten-pack",
                  "package_name": "10 sessions",
                  "services": [],
                  "sessions_total": 10,
                  "sessions_used": 2,
                  "sessions_left": 8,
                  "expires": "2027-11-11T01:15:00.000Z",
                  "status": "active",
                  "payment_id": 17,
                  "created": "2026-11-11T01:15:00.000Z"
                },
                "note": "Granted. package.purchased is sent."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/customers": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "listBookingCustomers",
        "summary": "The customers with appointments",
        "description": "Scope: `bookings:manage` (or `messages:read`). The people who have appointments, newest activity first, with visits, no-shows, upcoming count, packages left and the total paid. `q` searches name, e-mail and number; `tag` filters by a contact tag. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Name, e-mail or number contains this.",
            "type": "string",
            "x-example": "smith"
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only contacts with this tag.",
            "type": "string",
            "x-example": "vip"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "recent (default), name or visits.",
            "type": "string",
            "enum": [
              "recent",
              "name",
              "visits"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The customers.",
            "schema": {
              "$ref": "#/definitions/CustomersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c1cl0",
                "customers": [
                  {
                    "contact": "61412345678",
                    "name": "John Smith",
                    "email": "john@example.com",
                    "tags": [
                      "vip"
                    ],
                    "visits": 6,
                    "no_shows": 0,
                    "upcoming": 1,
                    "last_visit": "2026-10-20T23:00:00.000Z",
                    "next_start": "2026-11-12T23:00:00.000Z",
                    "packages_left": 8,
                    "total_paid_label": "$240.00"
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/customers/{contact}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "getCustomerProfile",
        "summary": "A customer's whole profile",
        "description": "Scope: `bookings:manage` (or `messages:read`). Contact details and tags, upcoming and past appointments, internal notes and reminders, packages, payments, stats and the last 20 messages: one call for an agent that is about to talk to the customer.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "description": "The customer: number with country code, or business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "The profile.",
            "schema": {
              "$ref": "#/definitions/CustomerProfile"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c2cg1",
                "customer": {
                  "contact": "61412345678",
                  "name": "John Smith",
                  "email": "john@example.com",
                  "tags": [
                    "vip"
                  ]
                },
                "stats": {
                  "visits": 6,
                  "no_shows": 0,
                  "cancellations": 1,
                  "total_paid_label": "$240.00"
                },
                "upcoming": [],
                "past": [],
                "notes": [
                  {
                    "id": 7,
                    "contact": "61412345678",
                    "appointment_id": 42,
                    "booking_reference": "BK-7Q3M2A",
                    "body": "Prefers the window seat.",
                    "author": "API key Planner",
                    "author_kind": "api",
                    "pinned": false,
                    "remind_at": null,
                    "created": "2026-11-11T01:12:09.000Z",
                    "updated": "2026-11-11T01:12:09.000Z"
                  }
                ],
                "reminders": [],
                "packages": [
                  {
                    "id": 5,
                    "contact": "61412345678",
                    "contact_name": "John Smith",
                    "package_id": "ten-pack",
                    "package_name": "10 sessions",
                    "services": [],
                    "sessions_total": 10,
                    "sessions_used": 2,
                    "sessions_left": 8,
                    "expires": "2027-11-11T01:15:00.000Z",
                    "status": "active",
                    "payment_id": 17,
                    "created": "2026-11-11T01:15:00.000Z"
                  }
                ],
                "payments": [
                  {
                    "id": 15,
                    "kind": "booking",
                    "status": "paid",
                    "provider": "stripe",
                    "amount": 40.0,
                    "amount_label": "$40.00",
                    "full_label": "$40.00",
                    "discount_label": "",
                    "coupon_code": "",
                    "currency": "USD",
                    "refunded": 0.0,
                    "refunded_label": "",
                    "description": "Haircut",
                    "contact": "61412345678",
                    "payer_name": "John Smith",
                    "appointment_id": 42,
                    "booking_reference": "BK-7Q3M2A",
                    "package_purchase_id": null,
                    "checkout_url": "",
                    "link_url": "",
                    "last_error": "",
                    "paid": "2026-11-11T01:15:00.000Z",
                    "refunded_at": null,
                    "created": "2026-11-11T01:10:00.000Z"
                  }
                ],
                "messages": [
                  {
                    "direction": "in",
                    "text": "Can I move Friday?",
                    "time": "2026-11-10T22:00:00.000Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Payments"
        ],
        "operationId": "updateCustomer",
        "summary": "Change a customer's name, e-mail, tags or fields",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. Updates the contact record (made when there is none). The e-mail also goes onto the customer's upcoming confirmed appointments so their e-mails reach the new address.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "description": "The customer: number with country code, or business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CustomerPatchRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/CustomerResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c3cu2",
                "customer": {
                  "contact": "61412345678",
                  "name": "John Smith",
                  "email": "john.new@example.com",
                  "tags": [
                    "vip",
                    "colour"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Payments"
        ],
        "operationId": "eraseCustomerBookingData",
        "summary": "Erase a customer's booking data",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. For a privacy request. Future confirmed appointments are cancelled without a message (reason \"data erased\"); every appointment of the customer loses their number, name, e-mail, notes and answers (the row stays, anonymised, so reports still count it); their notes, links, holds and poll votes are deleted; package purchases and payments keep amounts and dates but lose the customer. The contact record and the conversation are kept: `DELETE /contacts/{identity}?booking_data=erase` removes the contact too. `booking.customer.erased` is sent. It cannot be undone.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "contact",
            "in": "path",
            "required": true,
            "description": "The customer: number with country code, or business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          }
        ],
        "responses": {
          "200": {
            "description": "Erased.",
            "schema": {
              "$ref": "#/definitions/CustomerEraseResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4ce3",
                "erased": true,
                "counts": {
                  "appointments": 4,
                  "cancelled": 1,
                  "notes": 2,
                  "links": 1,
                  "holds": 0,
                  "votes": 0,
                  "packages": 0,
                  "payments": 1
                },
                "note": "The customer's appointments, notes, links, holds and poll votes were erased or anonymised."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/polls": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "listPolls",
        "summary": "The meeting polls",
        "description": "Scope: `bookings:manage` (or `messages:read`). Newest first, with options, votes and status.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only this status.",
            "type": "string",
            "enum": [
              "open",
              "closed",
              "booked"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          }
        ],
        "responses": {
          "200": {
            "description": "The polls.",
            "schema": {
              "$ref": "#/definitions/PollsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q1pl4",
                "polls": [
                  {
                    "id": 12,
                    "title": "Team planning",
                    "description": "",
                    "service_id": "consultation",
                    "provider_id": "",
                    "duration_min": 60,
                    "options": [
                      {
                        "id": "a",
                        "start": "2026-11-11T23:00:00.000Z",
                        "end": "2026-11-12T00:00:00.000Z",
                        "start_local": "2026-11-12T10:00",
                        "end_local": "2026-11-12T11:00",
                        "votes": 2,
                        "voters": [
                          "Sam",
                          "Alex"
                        ]
                      },
                      {
                        "id": "b",
                        "start": "2026-11-12T03:00:00.000Z",
                        "end": "2026-11-12T04:00:00.000Z",
                        "start_local": "2026-11-12T14:00",
                        "end_local": "2026-11-12T15:00",
                        "votes": 1,
                        "voters": [
                          "Sam"
                        ]
                      }
                    ],
                    "votes": [
                      {
                        "name": "Sam",
                        "contact": "61412345678",
                        "email": null,
                        "choices": [
                          "a",
                          "b"
                        ],
                        "comment": "",
                        "created": "2026-11-11T02:00:00.000Z"
                      }
                    ],
                    "contact": "",
                    "contact_name": "",
                    "status": "open",
                    "chosen_option": "",
                    "appointment_id": null,
                    "url": "https://www.app2email.com/book/pQ4rT7uV9wXy",
                    "closes": "2026-11-12T00:00:00.000Z",
                    "created": "2026-11-11T01:00:00.000Z"
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "createPoll",
        "summary": "Offer several times and let people vote",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. 2 to 10 possible start times (each free now; the business's rule: inside the opening hours), a title, a service or a length. The times are not held. Share the `url`: people open it and vote. Pick the winner with POST /bookings/polls/{id}/book. `poll.voted` is sent for each vote. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PollCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/PollResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q2pc5",
                "poll": {
                  "id": 12,
                  "title": "Team planning",
                  "description": "",
                  "service_id": "consultation",
                  "provider_id": "",
                  "duration_min": 60,
                  "options": [
                    {
                      "id": "a",
                      "start": "2026-11-11T23:00:00.000Z",
                      "end": "2026-11-12T00:00:00.000Z",
                      "start_local": "2026-11-12T10:00",
                      "end_local": "2026-11-12T11:00",
                      "votes": 2,
                      "voters": [
                        "Sam",
                        "Alex"
                      ]
                    },
                    {
                      "id": "b",
                      "start": "2026-11-12T03:00:00.000Z",
                      "end": "2026-11-12T04:00:00.000Z",
                      "start_local": "2026-11-12T14:00",
                      "end_local": "2026-11-12T15:00",
                      "votes": 1,
                      "voters": [
                        "Sam"
                      ]
                    }
                  ],
                  "votes": [
                    {
                      "name": "Sam",
                      "contact": "61412345678",
                      "email": null,
                      "choices": [
                        "a",
                        "b"
                      ],
                      "comment": "",
                      "created": "2026-11-11T02:00:00.000Z"
                    }
                  ],
                  "contact": "",
                  "contact_name": "",
                  "status": "open",
                  "chosen_option": "",
                  "appointment_id": null,
                  "url": "https://www.app2email.com/book/pQ4rT7uV9wXy",
                  "closes": "2026-11-12T00:00:00.000Z",
                  "created": "2026-11-11T01:00:00.000Z"
                },
                "url": "https://www.app2email.com/book/pQ4rT7uV9wXy",
                "note": "Share the url: people open it and vote. The times are not held."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/polls/{id}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "getPoll",
        "summary": "One poll with its votes",
        "description": "Scope: `bookings:manage` (or `messages:read`). The options with their vote counts and voters, and every vote with the voter's name, number and comment.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The poll's id.",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "The poll.",
            "schema": {
              "$ref": "#/definitions/PollResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q3pg6",
                "poll": {
                  "id": 12,
                  "title": "Team planning",
                  "description": "",
                  "service_id": "consultation",
                  "provider_id": "",
                  "duration_min": 60,
                  "options": [
                    {
                      "id": "a",
                      "start": "2026-11-11T23:00:00.000Z",
                      "end": "2026-11-12T00:00:00.000Z",
                      "start_local": "2026-11-12T10:00",
                      "end_local": "2026-11-12T11:00",
                      "votes": 2,
                      "voters": [
                        "Sam",
                        "Alex"
                      ]
                    },
                    {
                      "id": "b",
                      "start": "2026-11-12T03:00:00.000Z",
                      "end": "2026-11-12T04:00:00.000Z",
                      "start_local": "2026-11-12T14:00",
                      "end_local": "2026-11-12T15:00",
                      "votes": 1,
                      "voters": [
                        "Sam"
                      ]
                    }
                  ],
                  "votes": [
                    {
                      "name": "Sam",
                      "contact": "61412345678",
                      "email": null,
                      "choices": [
                        "a",
                        "b"
                      ],
                      "comment": "",
                      "created": "2026-11-11T02:00:00.000Z"
                    }
                  ],
                  "contact": "",
                  "contact_name": "",
                  "status": "open",
                  "chosen_option": "",
                  "appointment_id": null,
                  "url": "https://www.app2email.com/book/pQ4rT7uV9wXy",
                  "closes": "2026-11-12T00:00:00.000Z",
                  "created": "2026-11-11T01:00:00.000Z"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/polls/{id}/close": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "closePoll",
        "summary": "Close a poll to new votes",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. No more votes. `poll.closed` is sent with status `closed`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The poll's id.",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "Closed.",
            "schema": {
              "$ref": "#/definitions/PollResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q4pk7",
                "poll": {
                  "id": 12,
                  "title": "Team planning",
                  "description": "",
                  "service_id": "consultation",
                  "provider_id": "",
                  "duration_min": 60,
                  "options": [
                    {
                      "id": "a",
                      "start": "2026-11-11T23:00:00.000Z",
                      "end": "2026-11-12T00:00:00.000Z",
                      "start_local": "2026-11-12T10:00",
                      "end_local": "2026-11-12T11:00",
                      "votes": 2,
                      "voters": [
                        "Sam",
                        "Alex"
                      ]
                    },
                    {
                      "id": "b",
                      "start": "2026-11-12T03:00:00.000Z",
                      "end": "2026-11-12T04:00:00.000Z",
                      "start_local": "2026-11-12T14:00",
                      "end_local": "2026-11-12T15:00",
                      "votes": 1,
                      "voters": [
                        "Sam"
                      ]
                    }
                  ],
                  "votes": [
                    {
                      "name": "Sam",
                      "contact": "61412345678",
                      "email": null,
                      "choices": [
                        "a",
                        "b"
                      ],
                      "comment": "",
                      "created": "2026-11-11T02:00:00.000Z"
                    }
                  ],
                  "contact": "",
                  "contact_name": "",
                  "status": "closed",
                  "chosen_option": "",
                  "appointment_id": null,
                  "url": "https://www.app2email.com/book/pQ4rT7uV9wXy",
                  "closes": "2026-11-12T00:00:00.000Z",
                  "created": "2026-11-11T01:00:00.000Z"
                },
                "note": "Closed: no more votes. poll.closed is sent."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/bookings/polls/{id}/book": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "bookPoll",
        "summary": "Pick the winning time",
        "description": "Scope: `bookings:manage`. Not with a sandbox key. The option is checked like a business booking (409 `booking_slot_taken` when it is not free any more). With a main contact an appointment is made for them (source dashboard; the normal WhatsApp confirmation unless `notify` is false); without one the time is blocked in the calendar under the poll's title. The poll becomes `booked` and `poll.closed` is sent with the chosen option. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The poll's id.",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PollBookRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Booked.",
            "schema": {
              "$ref": "#/definitions/PollBookResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "q5pb8",
                "poll": {
                  "id": 12,
                  "title": "Team planning",
                  "description": "",
                  "service_id": "consultation",
                  "provider_id": "",
                  "duration_min": 60,
                  "options": [
                    {
                      "id": "a",
                      "start": "2026-11-11T23:00:00.000Z",
                      "end": "2026-11-12T00:00:00.000Z",
                      "start_local": "2026-11-12T10:00",
                      "end_local": "2026-11-12T11:00",
                      "votes": 2,
                      "voters": [
                        "Sam",
                        "Alex"
                      ]
                    },
                    {
                      "id": "b",
                      "start": "2026-11-12T03:00:00.000Z",
                      "end": "2026-11-12T04:00:00.000Z",
                      "start_local": "2026-11-12T14:00",
                      "end_local": "2026-11-12T15:00",
                      "votes": 1,
                      "voters": [
                        "Sam"
                      ]
                    }
                  ],
                  "votes": [
                    {
                      "name": "Sam",
                      "contact": "61412345678",
                      "email": null,
                      "choices": [
                        "a",
                        "b"
                      ],
                      "comment": "",
                      "created": "2026-11-11T02:00:00.000Z"
                    }
                  ],
                  "contact": "",
                  "contact_name": "",
                  "status": "booked",
                  "chosen_option": "a",
                  "appointment_id": null,
                  "url": "https://www.app2email.com/book/pQ4rT7uV9wXy",
                  "closes": "2026-11-12T00:00:00.000Z",
                  "created": "2026-11-11T01:00:00.000Z"
                },
                "booking": null,
                "block": null,
                "note": "The time is blocked in the calendar (the poll has no contact)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "getShop",
        "summary": "The shop: on or off, open now, the order page, counts and limits",
        "description": "Scope: `orders:manage`. Start here. `enabled` says whether the shop takes orders; `open_now` and `paused` what a customer would find right now; `page_url` is the public order page; `counts` and `limits` say how big the catalog is and may get (10,000 items, archived ones not counted). A number that never opened Order-and-Pay answers `set_up` false.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The shop.",
            "schema": {
              "$ref": "#/definitions/ShopResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h1shp",
                "shop": {
                  "set_up": true,
                  "enabled": true,
                  "name": "Sample Pizza",
                  "preset": "takeaway",
                  "currency": "USD",
                  "timezone": "Australia/Sydney",
                  "page_url": "https://www.app2email.com/shop/sample-pizza",
                  "open_now": true,
                  "paused": false,
                  "pickup": true,
                  "delivery": false,
                  "browse": "page",
                  "counts": {
                    "items": 42,
                    "active": 40,
                    "categories": 5
                  },
                  "limits": {
                    "items": 10000,
                    "categories": 500,
                    "variants": 250,
                    "search_limit": 100
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/settings": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "getShopSettings",
        "summary": "Every setting of the shop, as the shop uses it",
        "description": "Scope: `orders:manage`. `config` holds the sections with every value in force: `fulfilment` (pickup, delivery, opening hours, special days, the pause), `pickup` (preparation time, time slots), `delivery` (the options with areas and costs), `checkout` (minimum order, fees, tips, notes), `payments`, `discounts` (codes), `orders` (automatic acceptance), `notify` (e-mail addresses), `whatsapp` (the words that open the shop, how customers order, the order messages), and `business`, `money`, `tax`, `stock`, `catalog`. A value the shop never changed shows the default of its type.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The settings. The example is shortened.",
            "schema": {
              "$ref": "#/definitions/ShopSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h2set",
                "settings": {
                  "enabled": true,
                  "slug": "sample-pizza",
                  "page_url": "https://www.app2email.com/shop/sample-pizza",
                  "config": {
                    "fulfilment": {
                      "pickup": true,
                      "delivery": false,
                      "pause_until": "",
                      "pause_reason": ""
                    },
                    "pickup": {
                      "prep_minutes": 20,
                      "asap": true,
                      "slots": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "updateShopSettings",
        "summary": "Change settings of the shop",
        "description": "Scope: `orders:manage`. Not with a sandbox key. Send `config` with the sections to change and, in each, only the keys to change: an object is merged key by key, a list replaces the stored list. Example: pause the shop for half an hour with `{\"config\": {\"fulfilment\": {\"pause_until\": \"2026-11-14T12:30:00Z\", \"pause_reason\": \"Kitchen is full\"}}}`. The whole result is checked before anything is saved: 400 `shop_invalid` names the first problem and `error.details.problems` all of them. The currency cannot change while the shop has items. The switch (`enabled`) and the order page's address are set in the dashboard, where they have their own checks. `not_ready` in the answer lists what still keeps the shop from taking orders.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopSettingsRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The settings after the change.",
            "schema": {
              "$ref": "#/definitions/ShopSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h3put",
                "settings": {
                  "enabled": true,
                  "slug": "sample-pizza",
                  "page_url": "https://www.app2email.com/shop/sample-pizza",
                  "config": {
                    "fulfilment": {
                      "pickup": true,
                      "delivery": false,
                      "pause_until": "2026-11-14T12:30:00Z",
                      "pause_reason": "Kitchen is full"
                    }
                  }
                },
                "not_ready": []
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/categories": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "listShopCategories",
        "summary": "The categories of the catalog",
        "description": "Scope: `orders:manage`. Two levels at most (`parent_id`). `items` counts the items of each; `hidden` categories are not shown to customers.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The categories.",
            "schema": {
              "$ref": "#/definitions/ShopCategoriesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h4cat",
                "categories": [
                  {
                    "id": 3,
                    "parent_id": null,
                    "name": "Pizza",
                    "slug": "pizza",
                    "sort": 1,
                    "hidden": false,
                    "items": 12
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/items": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "listShopItems",
        "summary": "Search and filter the products",
        "description": "Scope: `orders:manage`. The same search customers use: `q` finds words in the name, description, SKU and tags and tolerates typing mistakes (`typo_match` true). Filter by `category`, `tags`, a price range, `in_stock`, and any attribute with `attr.<key>=<value>` (eg `attr.colour=red,blue`). Without `status` only items customers can buy are listed; `status=any` adds hidden ones, `status=archived` lists the archive. Page with `limit` and `offset`; `total` stops counting at a few thousand (`total_capped`). `facets=1` adds the counts per attribute value, tag and the price range of the result. Variants and option groups are in GET /shop/items/{id}.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Words to search for.",
            "type": "string",
            "x-example": "margherita"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Only this category (its id).",
            "type": "integer",
            "x-example": 3
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "Only items with all of these tags, separated by commas.",
            "type": "string",
            "x-example": "vegetarian"
          },
          {
            "name": "price_min",
            "in": "query",
            "required": false,
            "description": "Lowest price, minor units.",
            "type": "integer"
          },
          {
            "name": "price_max",
            "in": "query",
            "required": false,
            "description": "Highest price, minor units.",
            "type": "integer",
            "x-example": 3000
          },
          {
            "name": "in_stock",
            "in": "query",
            "required": false,
            "description": "1 = leave out what is sold out.",
            "type": "string",
            "enum": [
              "1",
              "0"
            ]
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "active (default), hidden, archived, or any (everything but archived).",
            "type": "string",
            "enum": [
              "active",
              "hidden",
              "archived",
              "any"
            ]
          },
          {
            "name": "stock",
            "in": "query",
            "required": false,
            "description": "Only items in this stock state.",
            "type": "string",
            "enum": [
              "low",
              "out",
              "untracked"
            ]
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "relevance (default with q), manual (the shop's own order), price_asc, price_desc, newest, best, name.",
            "type": "string",
            "enum": [
              "relevance",
              "manual",
              "price_asc",
              "price_desc",
              "newest",
              "best",
              "name"
            ]
          },
          {
            "name": "facets",
            "in": "query",
            "required": false,
            "description": "1 = add the counts per attribute value and tag.",
            "type": "string",
            "enum": [
              "1",
              "0"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100, default 24).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 24
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many.",
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        ],
        "responses": {
          "200": {
            "description": "The items.",
            "schema": {
              "$ref": "#/definitions/ShopItemsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h5lst",
                "items": [
                  {
                    "id": 12,
                    "sku": "PZ-MARG",
                    "name": "Margherita",
                    "description": "Tomato, mozzarella, basil.",
                    "category_id": 3,
                    "price": 1000,
                    "price_label": "$10.00",
                    "compare_at": null,
                    "tax_class": "standard",
                    "status": "active",
                    "has_variants": false,
                    "tags": [
                      "vegetarian"
                    ],
                    "attrs": {},
                    "allergens": [
                      "gluten",
                      "milk"
                    ],
                    "dietary": [
                      "vegetarian"
                    ],
                    "track_stock": false,
                    "stock_qty": 0,
                    "low_stock_at": null,
                    "stock_state": "untracked",
                    "daily_limit": null,
                    "sold_out_until": null,
                    "sold_out_now": false,
                    "no_whatsapp": false,
                    "min_qty": 1,
                    "max_qty": 0,
                    "prep_minutes": null,
                    "sort": 0,
                    "sold_count": 41,
                    "image": null,
                    "created_at": "2026-11-13T01:00:00Z",
                    "updated_at": "2026-11-13T01:00:00Z"
                  }
                ],
                "total": 1,
                "total_capped": false,
                "typo_match": false,
                "limit": 24,
                "offset": 0,
                "facets": null,
                "currency": "USD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "createShopItem",
        "summary": "Add a product",
        "description": "Scope: `orders:manage`. Not with a sandbox key. The body is the item: `name` and `price` (minor units) are needed, everything else is optional. `variants` gives the versions of the item (size, colour), each with its `attrs`, optional `price` and own stock; `option_group_ids` links existing option groups (extras, choices). Customers see an `active` item at once. 409 `shop_sku_taken` when the SKU is in use, 409 `shop_limit` at 10,000 items. Pictures are added in the dashboard (or by an import with picture addresses).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopItemRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/ShopItemResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h6new",
                "item": {
                  "id": 12,
                  "sku": "PZ-MARG",
                  "name": "Margherita",
                  "description": "Tomato, mozzarella, basil.",
                  "category_id": 3,
                  "price": 1000,
                  "price_label": "$10.00",
                  "compare_at": null,
                  "tax_class": "standard",
                  "status": "active",
                  "has_variants": false,
                  "tags": [
                    "vegetarian"
                  ],
                  "attrs": {},
                  "allergens": [
                    "gluten",
                    "milk"
                  ],
                  "dietary": [
                    "vegetarian"
                  ],
                  "track_stock": false,
                  "stock_qty": 0,
                  "low_stock_at": null,
                  "stock_state": "untracked",
                  "daily_limit": null,
                  "sold_out_until": null,
                  "sold_out_now": false,
                  "no_whatsapp": false,
                  "min_qty": 1,
                  "max_qty": 0,
                  "prep_minutes": null,
                  "sort": 0,
                  "sold_count": 41,
                  "image": null,
                  "created_at": "2026-11-13T01:00:00Z",
                  "updated_at": "2026-11-13T01:00:00Z",
                  "variants": [],
                  "option_group_ids": [
                    10
                  ],
                  "images": [],
                  "option_groups": [
                    {
                      "id": 10,
                      "name": "Size",
                      "min_choices": 1,
                      "max_choices": 1,
                      "options": [
                        {
                          "id": 101,
                          "name": "Small",
                          "price_delta": 0,
                          "price_delta_label": "",
                          "sold_out_now": false,
                          "default_on": true
                        },
                        {
                          "id": 102,
                          "name": "Large",
                          "price_delta": 300,
                          "price_delta_label": "+$3.00",
                          "sold_out_now": false,
                          "default_on": false
                        }
                      ]
                    }
                  ]
                },
                "currency": "USD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/items/{id}": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "getShopItem",
        "summary": "One product with variants, option groups and pictures",
        "description": "Scope: `orders:manage`. Everything needed to put the item in a cart: `variants` (an item with `has_variants` needs a `variant_id` in the cart line), `option_groups` with their choices, price changes and how many must and may be chosen, the stock of the item or of each variant, and `images`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The item's id (GET /shop/items).",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "The item.",
            "schema": {
              "$ref": "#/definitions/ShopItemResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h7get",
                "item": {
                  "id": 12,
                  "sku": "PZ-MARG",
                  "name": "Margherita",
                  "description": "Tomato, mozzarella, basil.",
                  "category_id": 3,
                  "price": 1000,
                  "price_label": "$10.00",
                  "compare_at": null,
                  "tax_class": "standard",
                  "status": "active",
                  "has_variants": false,
                  "tags": [
                    "vegetarian"
                  ],
                  "attrs": {},
                  "allergens": [
                    "gluten",
                    "milk"
                  ],
                  "dietary": [
                    "vegetarian"
                  ],
                  "track_stock": false,
                  "stock_qty": 0,
                  "low_stock_at": null,
                  "stock_state": "untracked",
                  "daily_limit": null,
                  "sold_out_until": null,
                  "sold_out_now": false,
                  "no_whatsapp": false,
                  "min_qty": 1,
                  "max_qty": 0,
                  "prep_minutes": null,
                  "sort": 0,
                  "sold_count": 41,
                  "image": null,
                  "created_at": "2026-11-13T01:00:00Z",
                  "updated_at": "2026-11-13T01:00:00Z",
                  "variants": [],
                  "option_group_ids": [
                    10
                  ],
                  "images": [],
                  "option_groups": [
                    {
                      "id": 10,
                      "name": "Size",
                      "min_choices": 1,
                      "max_choices": 1,
                      "options": [
                        {
                          "id": 101,
                          "name": "Small",
                          "price_delta": 0,
                          "price_delta_label": "",
                          "sold_out_now": false,
                          "default_on": true
                        },
                        {
                          "id": 102,
                          "name": "Large",
                          "price_delta": 300,
                          "price_delta_label": "+$3.00",
                          "sold_out_now": false,
                          "default_on": false
                        }
                      ]
                    }
                  ]
                },
                "currency": "USD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "updateShopItem",
        "summary": "Change a product: only the keys sent change",
        "description": "Scope: `orders:manage`. Not with a sandbox key. Send the keys to change. `variants`, when sent, is the whole list: include the `id` of each variant to keep, leave one out to remove it. Stock figures are only written when the request names them (`stock_qty` of the item or of a variant); to change stock safely while orders come in use POST /shop/items/{id}/stock. `status` archived takes the item out of the catalog.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The item's id (GET /shop/items).",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopItemRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The item after the change.",
            "schema": {
              "$ref": "#/definitions/ShopItemResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h8put",
                "item": {
                  "id": 12,
                  "sku": "PZ-MARG",
                  "name": "Margherita",
                  "description": "Tomato, mozzarella, basil.",
                  "category_id": 3,
                  "price": 1100,
                  "price_label": "$11.00",
                  "compare_at": null,
                  "tax_class": "standard",
                  "status": "active",
                  "has_variants": false,
                  "tags": [
                    "vegetarian"
                  ],
                  "attrs": {},
                  "allergens": [
                    "gluten",
                    "milk"
                  ],
                  "dietary": [
                    "vegetarian"
                  ],
                  "track_stock": false,
                  "stock_qty": 0,
                  "low_stock_at": null,
                  "stock_state": "untracked",
                  "daily_limit": null,
                  "sold_out_until": null,
                  "sold_out_now": false,
                  "no_whatsapp": false,
                  "min_qty": 1,
                  "max_qty": 0,
                  "prep_minutes": null,
                  "sort": 0,
                  "sold_count": 41,
                  "image": null,
                  "created_at": "2026-11-13T01:00:00Z",
                  "updated_at": "2026-11-13T01:00:00Z",
                  "variants": [],
                  "option_group_ids": [
                    10
                  ],
                  "images": [],
                  "option_groups": [
                    {
                      "id": 10,
                      "name": "Size",
                      "min_choices": 1,
                      "max_choices": 1,
                      "options": [
                        {
                          "id": 101,
                          "name": "Small",
                          "price_delta": 0,
                          "price_delta_label": "",
                          "sold_out_now": false,
                          "default_on": true
                        },
                        {
                          "id": 102,
                          "name": "Large",
                          "price_delta": 300,
                          "price_delta_label": "+$3.00",
                          "sold_out_now": false,
                          "default_on": false
                        }
                      ]
                    }
                  ]
                },
                "currency": "USD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "archiveShopItem",
        "summary": "Archive a product",
        "description": "Scope: `orders:manage`. Not with a sandbox key. The item is archived, not erased: orders keep their lines and the reports their figures. Archived items are not counted against the 10,000 item limit. PUT with `status` active brings it back.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The item's id (GET /shop/items).",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "The archived item.",
            "schema": {
              "$ref": "#/definitions/ShopItemResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h9del",
                "item": {
                  "id": 12,
                  "sku": "PZ-MARG",
                  "name": "Margherita",
                  "description": "Tomato, mozzarella, basil.",
                  "category_id": 3,
                  "price": 1000,
                  "price_label": "$10.00",
                  "compare_at": null,
                  "tax_class": "standard",
                  "status": "archived",
                  "has_variants": false,
                  "tags": [
                    "vegetarian"
                  ],
                  "attrs": {},
                  "allergens": [
                    "gluten",
                    "milk"
                  ],
                  "dietary": [
                    "vegetarian"
                  ],
                  "track_stock": false,
                  "stock_qty": 0,
                  "low_stock_at": null,
                  "stock_state": "untracked",
                  "daily_limit": null,
                  "sold_out_until": null,
                  "sold_out_now": false,
                  "no_whatsapp": false,
                  "min_qty": 1,
                  "max_qty": 0,
                  "prep_minutes": null,
                  "sort": 0,
                  "sold_count": 41,
                  "image": null,
                  "created_at": "2026-11-13T01:00:00Z",
                  "updated_at": "2026-11-13T01:00:00Z",
                  "variants": [],
                  "option_group_ids": [
                    10
                  ],
                  "images": [],
                  "option_groups": [
                    {
                      "id": 10,
                      "name": "Size",
                      "min_choices": 1,
                      "max_choices": 1,
                      "options": [
                        {
                          "id": 101,
                          "name": "Small",
                          "price_delta": 0,
                          "price_delta_label": "",
                          "sold_out_now": false,
                          "default_on": true
                        },
                        {
                          "id": 102,
                          "name": "Large",
                          "price_delta": 300,
                          "price_delta_label": "+$3.00",
                          "sold_out_now": false,
                          "default_on": false
                        }
                      ]
                    }
                  ]
                },
                "currency": "USD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/items/{id}/stock": {
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "setShopStock",
        "summary": "Set or change the stock of a product",
        "description": "Scope: `orders:manage`. Not with a sandbox key. `mode` set writes the figure, `mode` add changes it by `value` (negative takes away) in one step that cannot lose a sale happening at the same moment. For an item with variants send `variant_id`. Every change is written to the stock history with the key's name and the `note`. 409 `shop_not_tracked` when the item does not count stock: send `start_tracking` true to switch it on with this figure.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The item's id (GET /shop/items).",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopStockRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stock after the change.",
            "schema": {
              "$ref": "#/definitions/ShopStockResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h10st",
                "item_id": 14,
                "variant_id": null,
                "stock_qty": 24
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/items/{id}/sold_out": {
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "setShopSoldOut",
        "summary": "Mark a product sold out for a while, or back",
        "description": "Scope: `orders:manage`. Not with a sandbox key. For items that do not count stock (a dish that ran out). `until`: `on` until switched back, `1h`, `2h`, `4h`, `today` (until the end of the shop's day), `off` to make it available again, or a later time. Customers see it greyed out or not at all, as the shop has chosen.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The item's id (GET /shop/items).",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopSoldOutRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Until when it is sold out.",
            "schema": {
              "$ref": "#/definitions/ShopSoldOutResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h11so",
                "item_id": 12,
                "sold_out_until": "2026-11-14T13:00:00Z",
                "sold_out_now": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/orders": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "listShopOrders",
        "summary": "The orders, newest first",
        "description": "Scope: `orders:manage`. `group` narrows the list: `open` (accepted, being prepared, ready, on the way, and new ones), `new` (waiting for the shop to accept), `waiting` (not paid or not confirmed yet), `done`, `cancelled`. `q` finds a reference, a name or a number. Lists leave out the lines: `items_text` says what was ordered in one line, GET /shop/orders/{id} has the rest. Page with `before` set to `next_before`. To follow orders without polling use the `order.*` webhook events.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "open, new, waiting, done or cancelled. Left out: all.",
            "type": "string",
            "enum": [
              "open",
              "new",
              "waiting",
              "done",
              "cancelled"
            ]
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "A reference, a customer's name or number.",
            "type": "string",
            "x-example": "SO-K7M2QX"
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "For the next page: next_before of the previous answer.",
            "type": "integer"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 100, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          }
        ],
        "responses": {
          "200": {
            "description": "The orders.",
            "schema": {
              "$ref": "#/definitions/ShopOrdersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h12ol",
                "orders": [
                  {
                    "id": 318,
                    "reference": "SO-K7M2QX",
                    "status": "accepted",
                    "status_text": "Accepted",
                    "source": "api",
                    "fulfilment": "pickup",
                    "asap": true,
                    "due_at": "2026-11-13T01:20:00Z",
                    "due_label": "today 12:20",
                    "slot_label": "",
                    "customer_name": "Sample Contact",
                    "customer_phone": "61412345678",
                    "customer_email": "",
                    "contact_identity": "61412345678",
                    "contact_verified": true,
                    "address": {},
                    "delivery_method": "",
                    "delivery_zone": "",
                    "note": "",
                    "allergy_note": "",
                    "items_count": 3,
                    "items_text": "2 x Margherita, 1 x Cola",
                    "currency": "USD",
                    "subtotal": 3050,
                    "discount": 0,
                    "discount_code": "",
                    "delivery_fee": 0,
                    "fees": 0,
                    "tip": 0,
                    "tax": 0,
                    "total": 3050,
                    "total_label": "$30.50",
                    "refunded": 0,
                    "refundable": 3050,
                    "payment_state": "on_pickup",
                    "payment_method": "",
                    "payment_id": null,
                    "pickup_code": "7KQ2",
                    "order_url": "https://www.app2email.com/o/Xk3mP9qR2sT7",
                    "actions": [
                      "preparing",
                      "ready",
                      "complete",
                      "cancel",
                      "time"
                    ],
                    "can_refund": false,
                    "late": false,
                    "created_at": "2026-11-13T01:00:00Z",
                    "accepted_at": "2026-11-13T01:00:00Z",
                    "ready_at": null,
                    "completed_at": null,
                    "cancelled_at": null,
                    "cancelled_by": "",
                    "cancel_reason": "",
                    "handed_by": "",
                    "handed_method": ""
                  }
                ],
                "more": false,
                "next_before": null
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "createShopOrder",
        "summary": "Place an order for a customer",
        "description": "Scope: `orders:manage`. Not with a sandbox key. For a system or an agent that takes the order itself. The cart is priced from the shop's data as it is now, stock is taken in the same step, and the order appears in the dashboard and the counter app like any other (`source` api). You vouch for `contact`: the order counts as that customer's own, and they get the shop's order messages on WhatsApp (confirmation with the pickup QR code, ready, and so on) where those are switched on. `pay` later = at pickup or on delivery; `pay` online answers `checkout_url`: send it to the customer, the order is confirmed (and `order.created` sent) when it is paid. Send `expected_total` with the total the customer agreed to: a different total answers 409 `shop_changed` with the new quote in `error.details.quote`. 409 `shop_order_problems` lists what is in the way the same way. The `Idempotency-Key` header (or `client_key`) makes a retry safe: the same key answers the same order with `repeated` true and status 200.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopOrderCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Placed.",
            "schema": {
              "$ref": "#/definitions/ShopOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h13oc",
                "order": {
                  "id": 318,
                  "reference": "SO-K7M2QX",
                  "status": "accepted",
                  "status_text": "Accepted",
                  "source": "api",
                  "fulfilment": "pickup",
                  "asap": true,
                  "due_at": "2026-11-13T01:20:00Z",
                  "due_label": "today 12:20",
                  "slot_label": "",
                  "customer_name": "Sample Contact",
                  "customer_phone": "61412345678",
                  "customer_email": "",
                  "contact_identity": "61412345678",
                  "contact_verified": true,
                  "address": {},
                  "delivery_method": "",
                  "delivery_zone": "",
                  "note": "",
                  "allergy_note": "",
                  "items_count": 3,
                  "items_text": "2 x Margherita, 1 x Cola",
                  "currency": "USD",
                  "subtotal": 3050,
                  "discount": 0,
                  "discount_code": "",
                  "delivery_fee": 0,
                  "fees": 0,
                  "tip": 0,
                  "tax": 0,
                  "total": 3050,
                  "total_label": "$30.50",
                  "refunded": 0,
                  "refundable": 3050,
                  "payment_state": "on_pickup",
                  "payment_method": "",
                  "payment_id": null,
                  "pickup_code": "7KQ2",
                  "order_url": "https://www.app2email.com/o/Xk3mP9qR2sT7",
                  "actions": [
                    "preparing",
                    "ready",
                    "complete",
                    "cancel",
                    "time"
                  ],
                  "can_refund": false,
                  "late": false,
                  "created_at": "2026-11-13T01:00:00Z",
                  "accepted_at": "2026-11-13T01:00:00Z",
                  "ready_at": null,
                  "completed_at": null,
                  "cancelled_at": null,
                  "cancelled_by": "",
                  "cancel_reason": "",
                  "handed_by": "",
                  "handed_method": "",
                  "lines": [
                    {
                      "id": 901,
                      "item_id": 12,
                      "variant_id": null,
                      "sku": "PZ-MARG",
                      "name": "Margherita",
                      "variant_label": "",
                      "options": [
                        {
                          "id": 102,
                          "group": "Size",
                          "name": "Large",
                          "price_delta": 300
                        }
                      ],
                      "qty": 2,
                      "unit_price": 1300,
                      "unit_price_label": "$13.00",
                      "line_total": 2600,
                      "line_total_label": "$26.00",
                      "note": ""
                    }
                  ]
                },
                "repeated": false,
                "checkout_url": "",
                "payment_id": null
              }
            }
          },
          "200": {
            "description": "This key was used before: the order it made.",
            "schema": {
              "$ref": "#/definitions/ShopOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h13od",
                "order": {
                  "id": 318,
                  "reference": "SO-K7M2QX",
                  "status": "accepted",
                  "status_text": "Accepted",
                  "source": "api",
                  "fulfilment": "pickup",
                  "asap": true,
                  "due_at": "2026-11-13T01:20:00Z",
                  "due_label": "today 12:20",
                  "slot_label": "",
                  "customer_name": "Sample Contact",
                  "customer_phone": "61412345678",
                  "customer_email": "",
                  "contact_identity": "61412345678",
                  "contact_verified": true,
                  "address": {},
                  "delivery_method": "",
                  "delivery_zone": "",
                  "note": "",
                  "allergy_note": "",
                  "items_count": 3,
                  "items_text": "2 x Margherita, 1 x Cola",
                  "currency": "USD",
                  "subtotal": 3050,
                  "discount": 0,
                  "discount_code": "",
                  "delivery_fee": 0,
                  "fees": 0,
                  "tip": 0,
                  "tax": 0,
                  "total": 3050,
                  "total_label": "$30.50",
                  "refunded": 0,
                  "refundable": 3050,
                  "payment_state": "on_pickup",
                  "payment_method": "",
                  "payment_id": null,
                  "pickup_code": "7KQ2",
                  "order_url": "https://www.app2email.com/o/Xk3mP9qR2sT7",
                  "actions": [
                    "preparing",
                    "ready",
                    "complete",
                    "cancel",
                    "time"
                  ],
                  "can_refund": false,
                  "late": false,
                  "created_at": "2026-11-13T01:00:00Z",
                  "accepted_at": "2026-11-13T01:00:00Z",
                  "ready_at": null,
                  "completed_at": null,
                  "cancelled_at": null,
                  "cancelled_by": "",
                  "cancel_reason": "",
                  "handed_by": "",
                  "handed_method": "",
                  "lines": [
                    {
                      "id": 901,
                      "item_id": 12,
                      "variant_id": null,
                      "sku": "PZ-MARG",
                      "name": "Margherita",
                      "variant_label": "",
                      "options": [
                        {
                          "id": 102,
                          "group": "Size",
                          "name": "Large",
                          "price_delta": 300
                        }
                      ],
                      "qty": 2,
                      "unit_price": 1300,
                      "unit_price_label": "$13.00",
                      "line_total": 2600,
                      "line_total_label": "$26.00",
                      "note": ""
                    }
                  ]
                },
                "repeated": true,
                "checkout_url": "",
                "payment_id": null
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/orders/{id}": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "getShopOrder",
        "summary": "One order with lines, payment, next steps and history",
        "description": "Scope: `orders:manage`. By id or by reference. `lines` with the chosen variant and options, the money, the pickup or delivery details, `actions` (what POST /shop/orders/{id}/action accepts now), `can_refund` with `refundable`, and `events`: who did what and when, on which device, including the hand-over at the counter.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id, or its reference (SO-K7M2QX).",
            "type": "string",
            "x-example": "SO-K7M2QX"
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "schema": {
              "$ref": "#/definitions/ShopOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h14og",
                "order": {
                  "id": 318,
                  "reference": "SO-K7M2QX",
                  "status": "accepted",
                  "status_text": "Accepted",
                  "source": "api",
                  "fulfilment": "pickup",
                  "asap": true,
                  "due_at": "2026-11-13T01:20:00Z",
                  "due_label": "today 12:20",
                  "slot_label": "",
                  "customer_name": "Sample Contact",
                  "customer_phone": "61412345678",
                  "customer_email": "",
                  "contact_identity": "61412345678",
                  "contact_verified": true,
                  "address": {},
                  "delivery_method": "",
                  "delivery_zone": "",
                  "note": "",
                  "allergy_note": "",
                  "items_count": 3,
                  "items_text": "2 x Margherita, 1 x Cola",
                  "currency": "USD",
                  "subtotal": 3050,
                  "discount": 0,
                  "discount_code": "",
                  "delivery_fee": 0,
                  "fees": 0,
                  "tip": 0,
                  "tax": 0,
                  "total": 3050,
                  "total_label": "$30.50",
                  "refunded": 0,
                  "refundable": 3050,
                  "payment_state": "on_pickup",
                  "payment_method": "",
                  "payment_id": null,
                  "pickup_code": "7KQ2",
                  "order_url": "https://www.app2email.com/o/Xk3mP9qR2sT7",
                  "actions": [
                    "preparing",
                    "ready",
                    "complete",
                    "cancel",
                    "time"
                  ],
                  "can_refund": false,
                  "late": false,
                  "created_at": "2026-11-13T01:00:00Z",
                  "accepted_at": "2026-11-13T01:00:00Z",
                  "ready_at": null,
                  "completed_at": null,
                  "cancelled_at": null,
                  "cancelled_by": "",
                  "cancel_reason": "",
                  "handed_by": "",
                  "handed_method": "",
                  "lines": [
                    {
                      "id": 901,
                      "item_id": 12,
                      "variant_id": null,
                      "sku": "PZ-MARG",
                      "name": "Margherita",
                      "variant_label": "",
                      "options": [
                        {
                          "id": 102,
                          "group": "Size",
                          "name": "Large",
                          "price_delta": 300
                        }
                      ],
                      "qty": 2,
                      "unit_price": 1300,
                      "unit_price_label": "$13.00",
                      "line_total": 2600,
                      "line_total_label": "$26.00",
                      "note": ""
                    }
                  ]
                },
                "events": [
                  {
                    "type": "placed",
                    "to_status": "new",
                    "by_name": "API key Till",
                    "at": "2026-11-13T01:00:00Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/orders/{id}/action": {
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "updateShopOrder",
        "summary": "Move an order on, change its time, cancel or decline it",
        "description": "Scope: `orders:manage`. Not with a sandbox key. `action`: `accept`, `preparing`, `ready`, `out_for_delivery`, `complete` (handed over or delivered), `time` with `minutes` (later, or negative for earlier), `cancel` or `reject` with a `reason`, `no_show` for a ready pickup that was never collected (it ends as not collected and counts as a no-show of that customer), and `hand_lines` with `lines` [{ `id`, `qty` }] to give some lines now and the rest later (only when the shop has switched on partial hand-over; the order stays open until `complete`). Only the steps in the order's `actions` are accepted; anything else answers 400 `shop_invalid`, and 409 `shop_changed` when someone else moved the order meanwhile. `cancel` and `reject` give the stock back (`restock` false keeps it) and, with `refund` true, refund a paid order; `notice` in the answer says when a refund did not go through. The customer is told on WhatsApp where the shop has that message switched on. The step is written to the order's history with the key's name.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id, or its reference (SO-K7M2QX).",
            "type": "string",
            "x-example": "SO-K7M2QX"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopOrderActionRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order after the step.",
            "schema": {
              "$ref": "#/definitions/ShopOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h15oa",
                "order": {
                  "id": 318,
                  "reference": "SO-K7M2QX",
                  "status": "ready",
                  "status_text": "Ready",
                  "source": "api",
                  "fulfilment": "pickup",
                  "asap": true,
                  "due_at": "2026-11-13T01:20:00Z",
                  "due_label": "today 12:20",
                  "slot_label": "",
                  "customer_name": "Sample Contact",
                  "customer_phone": "61412345678",
                  "customer_email": "",
                  "contact_identity": "61412345678",
                  "contact_verified": true,
                  "address": {},
                  "delivery_method": "",
                  "delivery_zone": "",
                  "note": "",
                  "allergy_note": "",
                  "items_count": 3,
                  "items_text": "2 x Margherita, 1 x Cola",
                  "currency": "USD",
                  "subtotal": 3050,
                  "discount": 0,
                  "discount_code": "",
                  "delivery_fee": 0,
                  "fees": 0,
                  "tip": 0,
                  "tax": 0,
                  "total": 3050,
                  "total_label": "$30.50",
                  "refunded": 0,
                  "refundable": 3050,
                  "payment_state": "on_pickup",
                  "payment_method": "",
                  "payment_id": null,
                  "pickup_code": "7KQ2",
                  "order_url": "https://www.app2email.com/o/Xk3mP9qR2sT7",
                  "actions": [
                    "preparing",
                    "ready",
                    "complete",
                    "cancel",
                    "time"
                  ],
                  "can_refund": false,
                  "late": false,
                  "created_at": "2026-11-13T01:00:00Z",
                  "accepted_at": "2026-11-13T01:00:00Z",
                  "ready_at": null,
                  "completed_at": null,
                  "cancelled_at": null,
                  "cancelled_by": "",
                  "cancel_reason": "",
                  "handed_by": "",
                  "handed_method": "",
                  "lines": [
                    {
                      "id": 901,
                      "item_id": 12,
                      "variant_id": null,
                      "sku": "PZ-MARG",
                      "name": "Margherita",
                      "variant_label": "",
                      "options": [
                        {
                          "id": 102,
                          "group": "Size",
                          "name": "Large",
                          "price_delta": 300
                        }
                      ],
                      "qty": 2,
                      "unit_price": 1300,
                      "unit_price_label": "$13.00",
                      "line_total": 2600,
                      "line_total_label": "$26.00",
                      "note": ""
                    }
                  ]
                },
                "notice": ""
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/orders/{id}/refund": {
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "refundShopOrder",
        "summary": "Refund an order that was paid online",
        "description": "Scope: `orders:manage`. Not with a sandbox key. In full when `amount` is left out, else that many minor units (at most `refundable`). The money goes back through the payment provider the way it was paid; an order paid at the counter cannot be refunded here. The order itself stays as it is: cancel it with POST /shop/orders/{id}/action when it should also end.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id, or its reference (SO-K7M2QX).",
            "type": "string",
            "x-example": "SO-K7M2QX"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/ShopRefundRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order after the refund.",
            "schema": {
              "$ref": "#/definitions/ShopOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h16rf",
                "order": {
                  "id": 318,
                  "reference": "SO-K7M2QX",
                  "status": "accepted",
                  "status_text": "Accepted",
                  "source": "api",
                  "fulfilment": "pickup",
                  "asap": true,
                  "due_at": "2026-11-13T01:20:00Z",
                  "due_label": "today 12:20",
                  "slot_label": "",
                  "customer_name": "Sample Contact",
                  "customer_phone": "61412345678",
                  "customer_email": "",
                  "contact_identity": "61412345678",
                  "contact_verified": true,
                  "address": {},
                  "delivery_method": "",
                  "delivery_zone": "",
                  "note": "",
                  "allergy_note": "",
                  "items_count": 3,
                  "items_text": "2 x Margherita, 1 x Cola",
                  "currency": "USD",
                  "subtotal": 3050,
                  "discount": 0,
                  "discount_code": "",
                  "delivery_fee": 0,
                  "fees": 0,
                  "tip": 0,
                  "tax": 0,
                  "total": 3050,
                  "total_label": "$30.50",
                  "refunded": 3050,
                  "refundable": 0,
                  "payment_state": "refunded",
                  "payment_method": "stripe",
                  "payment_id": null,
                  "pickup_code": "7KQ2",
                  "order_url": "https://www.app2email.com/o/Xk3mP9qR2sT7",
                  "actions": [
                    "preparing",
                    "ready",
                    "complete",
                    "cancel",
                    "time"
                  ],
                  "can_refund": false,
                  "late": false,
                  "created_at": "2026-11-13T01:00:00Z",
                  "accepted_at": "2026-11-13T01:00:00Z",
                  "ready_at": null,
                  "completed_at": null,
                  "cancelled_at": null,
                  "cancelled_by": "",
                  "cancel_reason": "",
                  "handed_by": "",
                  "handed_method": "",
                  "lines": [
                    {
                      "id": 901,
                      "item_id": 12,
                      "variant_id": null,
                      "sku": "PZ-MARG",
                      "name": "Margherita",
                      "variant_label": "",
                      "options": [
                        {
                          "id": 102,
                          "group": "Size",
                          "name": "Large",
                          "price_delta": 300
                        }
                      ],
                      "qty": 2,
                      "unit_price": 1300,
                      "unit_price_label": "$13.00",
                      "line_total": 2600,
                      "line_total_label": "$26.00",
                      "note": ""
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/quote": {
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "quoteShopOrder",
        "summary": "Price a cart: total, problems, times and ways to pay",
        "description": "Scope: `orders:manage`. Nothing is saved and no stock is taken. `quote` has the lines with their prices, the discount (or why a code gives none), the delivery fee for the address, fees, tip, tax and `total`; `problems` lists what is in the way (empty = the order can be placed). `times` says whether as-soon-as-possible is offered and when it would be ready, and the time slots when the shop uses them; `pay` which ways to pay this order has. Quote first, show the total, then POST /shop/orders with `expected_total`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopQuoteRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The quote.",
            "schema": {
              "$ref": "#/definitions/ShopQuoteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h17qt",
                "quote": {
                  "currency": "USD",
                  "lines": [],
                  "items_count": 3,
                  "subtotal": 3050,
                  "discount": 0,
                  "discount_code": "",
                  "discount_message": "",
                  "fulfilment": "pickup",
                  "delivery_fee": 0,
                  "delivery_method": "",
                  "delivery_zone": "",
                  "fees_total": 0,
                  "tip": 0,
                  "tax": 0,
                  "tax_included": true,
                  "total": 3050,
                  "total_label": "$30.50",
                  "prep_minutes": 20,
                  "ok": true,
                  "problems": []
                },
                "times": {
                  "asap": {
                    "offered": true,
                    "ok": true,
                    "ready_label": "about 12:20",
                    "message": ""
                  },
                  "slots_on": false,
                  "days": [],
                  "open_now": true,
                  "paused": false
                },
                "pay": {
                  "online": [
                    "stripe"
                  ],
                  "later": true,
                  "must_prepay": false,
                  "free": false
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/report": {
      "get": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "getShopReport",
        "summary": "The shop's figures for a range of days",
        "description": "Scope: `orders:manage`. Both days are included, in the shop's time zone; the default is the last 7 days and a range covers 366 days at most. Orders by state, sales, what was paid online and at the counter by cash and card, delivery fees, tips, discounts, tax and refunds, the best sellers, orders per hour and per day, the customers who spent most, the discount codes used, where the orders came from, and the hand-over log.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "First day, YYYY-MM-DD. Default: six days before to.",
            "type": "string",
            "x-example": "2026-11-07"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Last day, YYYY-MM-DD. Default: today.",
            "type": "string",
            "x-example": "2026-11-13"
          }
        ],
        "responses": {
          "200": {
            "description": "The figures. The example is shortened.",
            "schema": {
              "$ref": "#/definitions/ShopReportResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h18rp",
                "report": {
                  "from": "2026-11-07",
                  "to": "2026-11-13",
                  "timezone": "Australia/Sydney",
                  "orders": {
                    "placed": 61,
                    "completed": 55,
                    "cancelled": 4
                  },
                  "money": {
                    "sales_label": "$1,840.50"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/shop/link": {
      "post": {
        "tags": [
          "Order-and-Pay"
        ],
        "operationId": "getShopOrderLink",
        "summary": "A customer's personal link to the order page",
        "description": "Scope: `orders:manage`. The order page opened through this link knows the customer: their name, their last five delivery addresses and their orders are there, and an order placed needs no confirmation step. Valid for 7 days. It identifies the customer, so send it only to that customer (for example in a template message). `page_url` is the public page without the personal part.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/ShopLinkRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The link.",
            "schema": {
              "$ref": "#/definitions/ShopLinkResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "h19lk",
                "url": "https://www.app2email.com/shop/sample-pizza?t=eyJ...",
                "page_url": "https://www.app2email.com/shop/sample-pizza",
                "days": 7,
                "enabled": true
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/guide": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getSubmitGuide",
        "summary": "The Submit-Info guide for agents: every key, rule and example",
        "description": "Scope: `submissions:manage`. Start here. One JSON document with everything needed to set Submit-Info up without reading anything else: every key of a form definition with its default and limit, the field types and how WhatsApp shows each, stage rules, rule operators, the automation triggers and actions with their keys and an example each, placeholders, formula functions, connection kinds, roles and abilities, limits, the presets, and three complete worked setups. `this_number` names the forms, lists and connections the number already has, so nothing is replaced by accident. Next: write a setup document and send it to POST /submit/setup with `dry_run` true.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The guide. The example is shortened.",
            "schema": {
              "$ref": "#/definitions/SubmitGuideResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "g1gde",
                "guide": {
                  "product": "Submit-Info",
                  "summary": "A form is a plain list of questions in steps. app2email turns it into a WhatsApp Flow and a web page with the same steps. Each filled-in form is a submission: answers, files, a reference and a public status page. A submission moves through the form's stages, can be assigned, noted, answered and exported. Automations (when - if - do) react to what happens: they reply, e-mail, change the stage, calculate, and call outside systems. Outside systems are reached through connections: a plain HTTP request, an operation of an OpenAPI document, or a tool of an MCP server.",
                  "how_to": [
                    "1. GET /guide (this document). Pick a preset from `presets` (GET /presets?key=<key> returns its complete setup document) or write your own.",
                    "2. POST /setup with \"dry_run\": true: nothing is saved; `problems` lists every problem with its path and a fix.",
                    "3. POST /setup without dry_run when `problems` is empty. Existing forms, lists and connections with the same key are replaced.",
                    "4. POST /forms/{key}/publish uploads the generated Flow to WhatsApp and publishes it (or list the keys under \"publish\" in the setup document).",
                    "5. Share links.wa_me or links.web of the form (GET /forms/{key}), or send it to a contact with POST /forms/{key}/send."
                  ],
                  "form": {
                    "keys": {
                      "title": "required. 1-60 characters. the form's public name",
                      "stages": "2-12 stages; the first is where a new submission starts. left out = New, In progress, Done"
                    },
                    "key_rule": "keys of steps, fields, stages and calculated values: a lower-case letter, then up to 39 of a-z, 0-9 and _. fields and calculated values share one set of keys",
                    "field_keys": {
                      "key": "required. a lower-case letter, then up to 39 of a-z, 0-9 and _; unique in the form; not a reserved word",
                      "required": "true = must be answered. default false"
                    },
                    "field_types": [
                      {
                        "type": "number",
                        "value": "number",
                        "keys": {
                          "min": "a number or null",
                          "max": "a number or null",
                          "decimals": "0-6; 0 = whole numbers",
                          "unit": "shown after the value, max 20 characters"
                        },
                        "whatsapp": "TextInput (number)",
                        "notes": "A number. With decimals the phone shows a text keyboard and the server checks the number."
                      }
                    ],
                    "internal_types": [
                      "text",
                      "textarea",
                      "number",
                      "email",
                      "phone",
                      "date",
                      "select",
                      "multiselect",
                      "yesno",
                      "rating"
                    ],
                    "reserved_keys": [
                      "reference",
                      "status",
                      "status_name",
                      "form",
                      "form_key",
                      "channel",
                      "contact",
                      "link",
                      "id",
                      "created",
                      "updated",
                      "assignee",
                      "priority",
                      "tags",
                      "due",
                      "files",
                      "flow_token",
                      "screen",
                      "error_message",
                      "error",
                      "answers",
                      "extra",
                      "submission",
                      "note",
                      "button",
                      "business",
                      "desk_link",
                      "status_kind",
                      "verified",
                      "files_count",
                      "prefill",
                      "confirm",
                      "true",
                      "false",
                      "null",
                      "and",
                      "or",
                      "not"
                    ],
                    "whatsapp": "the Flow is generated: one screen per step (a step with several photo / document fields is split, one picker per screen).",
                    "stage": {
                      "keys": {
                        "key": "required. a lower-case letter, then up to 39 of a-z, 0-9 and _",
                        "kind": "open | done | cancelled. at least one open and one done stage"
                      },
                      "example": {
                        "key": "approved",
                        "name": "Approved",
                        "kind": "done",
                        "color": "green",
                        "set_by": [
                          "manager"
                        ],
                        "require_note": true,
                        "message": "Your application {reference} is approved. {note}"
                      }
                    },
                    "rule": {
                      "shape": "{ \"field\": \"<key>\", <operator>: <value> } with one or more operators (every one must hold), or { \"all\": [rules] }, or { \"any\": [rules] }.",
                      "operators": [
                        "equals",
                        "not_equals",
                        "in",
                        "not_in",
                        "contains",
                        "empty",
                        "not_empty",
                        "gt",
                        "gte",
                        "lt",
                        "lte"
                      ],
                      "groups": "all | any",
                      "in_show_if": "`field` is a field of an EARLIER step that is asked or hidden",
                      "in_automations": "`field` is any field key or extra key, or status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone",
                      "example": {
                        "all": [
                          {
                            "field": "category",
                            "in": [
                              "outage",
                              "safety"
                            ]
                          },
                          {
                            "field": "amount",
                            "gt": 5000
                          }
                        ]
                      }
                    }
                  },
                  "automation": {
                    "keys": {
                      "name": "required. within one form a name is unique: setup replaces the automation with the same name",
                      "actions": "1-20 actions, run in order"
                    },
                    "triggers": [
                      {
                        "trigger": "status_changed",
                        "when": "the stage changed",
                        "options": {
                          "to": [],
                          "from": []
                        }
                      }
                    ],
                    "trigger_options": {
                      "status_changed.to": "stage keys the submission moved to; [] = any",
                      "overdue.minutes": "5 to 43200"
                    },
                    "actions": [
                      {
                        "type": "set_status",
                        "does": "moves the submission to a stage",
                        "keys": {
                          "status": "a stage key",
                          "note": "kept with the change; placeholders"
                        },
                        "example": {
                          "type": "set_status",
                          "status": "approved",
                          "note": ""
                        }
                      }
                    ],
                    "placeholders": [
                      {
                        "name": "{reference}",
                        "is": "the submission's reference, for example MR-7Q3M2A"
                      }
                    ],
                    "placeholder_notes": "a name that is not known stays as typed. in JSON bodies and arguments a string that is exactly one placeholder keeps the value's type (a number stays a number). in addresses each inserted value is percent-encoded",
                    "formula": {
                      "language": "numbers, 'texts', field keys, + - * / %, comparisons == != > >= < <=, and / or / not, brackets and the functions below.",
                      "functions": [
                        {
                          "name": "round",
                          "usage": "round(x, decimals)",
                          "does": "x rounded (half away from zero); decimals 0-10, default 0"
                        }
                      ],
                      "examples": [
                        "reading - previous('reading')",
                        "round(quantity * lookup('prices', product, 'price'), 2)"
                      ]
                    },
                    "json_path": "in `save`: $ = the whole answer, $.a.b[0].c = a value inside it, $text = the answer as text (MCP: the first text content)",
                    "limits": "a failed outside call is tried again after 1 minute, 10 minutes and 1 hour, then the webhook event submit.automation_failed is sent."
                  },
                  "connection": {
                    "keys": {
                      "kind": "http | openapi | mcp",
                      "base_url": "https only. for mcp: the server's address"
                    },
                    "kinds": [
                      {
                        "kind": "http",
                        "use": "a plain HTTP API: the action names method, path, query, headers and a JSON body"
                      }
                    ],
                    "auth_types": [
                      {
                        "type": "bearer",
                        "use": "Authorization: Bearer <secret>"
                      }
                    ],
                    "limits": {
                      "timeout_seconds": 15,
                      "answer_kb": 256,
                      "request_kb": 256,
                      "extra_headers": 5,
                      "functions": 300,
                      "params_per_function": 40,
                      "calls_per_minute": 60,
                      "calls_per_day": 2000,
                      "addresses": "https only; private, loopback, link-local and metadata addresses are refused; redirects are not followed"
                    },
                    "example": {
                      "key": "billing",
                      "name": "Billing",
                      "kind": "http",
                      "base_url": "https://billing.example.com/api",
                      "auth": {
                        "type": "bearer",
                        "secret": "<your token>"
                      },
                      "headers": {},
                      "enabled": true
                    }
                  },
                  "member": {
                    "keys": {
                      "email": "required: the invitation goes there",
                      "role": "admin | manager | agent | viewer: a starting set of abilities"
                    },
                    "roles": {
                      "owner": [
                        "note",
                        "reply",
                        "edit",
                        "stage",
                        "assign",
                        "files",
                        "export",
                        "delete",
                        "run",
                        "forms",
                        "automations",
                        "team"
                      ],
                      "admin": [
                        "note",
                        "reply",
                        "edit",
                        "stage",
                        "assign",
                        "files",
                        "export",
                        "delete",
                        "run",
                        "forms",
                        "automations",
                        "team"
                      ],
                      "manager": [
                        "note",
                        "reply",
                        "edit",
                        "stage",
                        "assign",
                        "files",
                        "export",
                        "delete",
                        "run"
                      ],
                      "agent": [
                        "note",
                        "reply",
                        "edit",
                        "stage",
                        "files",
                        "run"
                      ],
                      "viewer": []
                    },
                    "abilities": [
                      "note",
                      "reply",
                      "edit",
                      "stage",
                      "assign",
                      "files",
                      "export",
                      "delete",
                      "run",
                      "forms",
                      "automations",
                      "team"
                    ],
                    "notes": "seeing submissions is implied. an agent may assign to themselves only"
                  },
                  "settings": {
                    "enabled": "true switches Submit-Info on for the number",
                    "config": {
                      "default_prefix": "2-4 letters, default SI",
                      "retention_days": "0 = keep; else 30-3650"
                    }
                  },
                  "limits": {
                    "forms": 100,
                    "steps_per_form": 12,
                    "fields_per_step": 12,
                    "fields_per_form": 60,
                    "definition_kb": 64,
                    "stages_per_form": 12,
                    "lists": 50,
                    "items_per_list": 1000,
                    "list_kb": 200,
                    "list_items_shown_in_a_select": 200,
                    "automations": 200,
                    "actions_per_automation": 20,
                    "connections": 30,
                    "members": 200,
                    "files_per_submission": 60,
                    "file_mb_whatsapp": 25,
                    "file_mb_web_and_api": 10,
                    "answers_kb": 64,
                    "note_or_reply_characters": 4000,
                    "tags_per_submission": 20,
                    "tag_characters": 40,
                    "page": 50,
                    "page_max": 200,
                    "run_log_days": 30
                  },
                  "setup": {
                    "shape": "{ dry_run, settings: { enabled, config }, lists: [...], connections: [...], forms: [{ key, name, definition }], automations: [...], publish: [form keys] }. every part is optional",
                    "order": "lists and connections are applied first, then forms, then automations. with any problem nothing is written",
                    "replaces": "forms, lists and connections by key; automations by name within the same form"
                  },
                  "presets": [
                    {
                      "key": "quote",
                      "name": "Quote request",
                      "description": "What is needed, quantity, photos and address. Staff enter the amount; the customer accepts or declines with a button.",
                      "category": "Customers"
                    },
                    {
                      "key": "meter_reading",
                      "name": "Meter reading",
                      "description": "Meter number, reading and a photo. The usage since the last reading is calculated; odd readings are queried.",
                      "category": "Customers"
                    },
                    {
                      "key": "job_completed",
                      "name": "Job completed",
                      "description": "Field staff log a finished job: the job from a list, work done, parts, hours, photos and the location.",
                      "category": "Field staff"
                    }
                  ],
                  "examples": [
                    {
                      "title": "A quote request the customer accepts or declines with a button",
                      "setup": {
                        "dry_run": true,
                        "settings": {
                          "enabled": true
                        },
                        "lists": [
                          {
                            "key": "products",
                            "name": "Products",
                            "items": [
                              {
                                "id": "pump-s",
                                "title": "Pump, small",
                                "description": "Up to 40 l/min",
                                "price": 240
                              },
                              {
                                "id": "pump-l",
                                "title": "Pump, large",
                                "description": "Up to 120 l/min",
                                "price": 610
                              }
                            ]
                          }
                        ],
                        "connections": [
                          {
                            "name": "ERP",
                            "kind": "http",
                            "base_url": "https://erp.example.com/api",
                            "auth": {
                              "type": "bearer",
                              "secret": "YOUR_ERP_TOKEN"
                            },
                            "headers": {
                              "X-Tenant": "acme"
                            },
                            "enabled": true,
                            "key": "erp"
                          }
                        ],
                        "forms": [
                          {
                            "key": "quote",
                            "name": "Quote request",
                            "definition": {
                              "title": "Quote request",
                              "description": "Tell us what you need and we will send a price.",
                              "prefix": "QR",
                              "steps": [
                                {
                                  "key": "need",
                                  "title": "What you need",
                                  "text": "",
                                  "show_if": null,
                                  "fields": [
                                    {
                                      "key": "product",
                                      "type": "select",
                                      "label": "Product",
                                      "required": true,
                                      "list": "products"
                                    },
                                    {
                                      "key": "quantity",
                                      "type": "number",
                                      "label": "How many?",
                                      "required": true,
                                      "min": 1,
                                      "max": 10000,
                                      "decimals": 0
                                    },
                                    {
                                      "key": "notes",
                                      "type": "textarea",
                                      "label": "Anything we should know?",
                                      "required": false,
                                      "max_length": 1000
                                    },
                                    {
                                      "key": "photos",
                                      "type": "photo",
                                      "label": "Photos of the site (optional)",
                                      "required": false,
                                      "max_files": 3,
                                      "source": "any"
                                    },
                                    {
                                      "key": "quote_amount",
                                      "type": "number",
                                      "label": "Quote amount",
                                      "internal": true,
                                      "decimals": 2,
                                      "unit": "USD"
                                    }
                                  ]
                                },
                                {
                                  "key": "delivery",
                                  "title": "Delivery",
                                  "text": "",
                                  "show_if": null,
                                  "fields": [
                                    {
                                      "key": "deliver",
                                      "type": "yesno",
                                      "label": "Do you need delivery?",
                                      "required": true
                                    }
                                  ]
                                },
                                {
                                  "key": "delivery_address",
                                  "title": "Delivery address",
                                  "text": "",
                                  "show_if": {
                                    "field": "deliver",
                                    "equals": true
                                  },
                                  "fields": [
                                    {
                                      "key": "address",
                                      "type": "textarea",
                                      "label": "Where should we deliver?",
                                      "required": true,
                                      "max_length": 300
                                    }
                                  ]
                                }
                              ],
                              "stages": [
                                {
                                  "key": "new",
                                  "name": "New",
                                  "kind": "open",
                                  "color": "blue",
                                  "set_by": [],
                                  "require_note": false,
                                  "message": ""
                                },
                                {
                                  "key": "quoted",
                                  "name": "Quoted",
                                  "kind": "open",
                                  "color": "amber",
                                  "set_by": [],
                                  "require_note": false,
                                  "message": ""
                                },
                                {
                                  "key": "accepted",
                                  "name": "Accepted",
                                  "kind": "done",
                                  "color": "green",
                                  "set_by": [],
                                  "require_note": false,
                                  "message": "Thank you. We will be in touch about {reference} shortly."
                                },
                                {
                                  "key": "declined",
                                  "name": "Declined",
                                  "kind": "cancelled",
                                  "color": "grey",
                                  "set_by": [],
                                  "require_note": false,
                                  "message": ""
                                }
                              ],
                              "trigger": {
                                "words": [
                                  "quote"
                                ],
                                "header": "",
                                "body": "Tap the button to ask for a quote.",
                                "button": "Get a quote",
                                "footer": ""
                              },
                              "after": {
                                "review_step": true,
                                "reply": "Thanks {contact.name}. Your request {reference} is with us; the price follows shortly.",
                                "allow_additions": true,
                                "status_page": true
                              },
                              "calculated": [
                                {
                                  "key": "estimate",
                                  "label": "Estimate",
                                  "formula": "quantity * lookup('products', product, 'price')",
                                  "unit": "USD",
                                  "decimals": 2
                                }
                              ]
                            }
                          }
                        ],
                        "automations": [
                          {
                            "name": "Price a quote request in the ERP",
                            "form": "quote",
                            "enabled": true,
                            "trigger": "submitted",
                            "options": {},
                            "conditions": {
                              "all": [
                                {
                                  "field": "quantity",
                                  "gt": 0
                                }
                              ]
                            },
                            "actions": [
                              {
                                "type": "http",
                                "connection": "erp",
                                "method": "POST",
                                "path": "/quotes",
                                "query": {},
                                "headers": {
                                  "X-Source": "whatsapp"
                                },
                                "body": {
                                  "reference": "{reference}",
                                  "customer": {
                                    "name": "{contact.name}",
                                    "phone": "{contact.phone}"
                                  },
                                  "product": "{product}",
                                  "quantity": "{quantity}",
                                  "photos": "{files.photos}"
                                },
                                "save": {
                                  "erp_id": "$.id",
                                  "quote_amount": "$.total"
                                },
                                "on_fail": "retry"
                              },
                              {
                                "type": "set_status",
                                "status": "quoted",
                                "note": "Priced by the ERP"
                              },
                              {
                                "type": "reply",
                                "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                                "buttons": [
                                  {
                                    "id": "accept",
                                    "title": "Accept",
                                    "set_status": "accepted"
                                  },
                                  {
                                    "id": "decline",
                                    "title": "Decline",
                                    "set_status": "declined"
                                  }
                                ],
                                "file": "",
                                "link": true
                              }
                            ]
                          },
                          {
                            "name": "Tell the owner when a quote is accepted",
                            "form": "quote",
                            "enabled": true,
                            "trigger": "status_changed",
                            "options": {
                              "to": [
                                "accepted"
                              ],
                              "from": []
                            },
                            "conditions": null,
                            "actions": [
                              {
                                "type": "email",
                                "to": [
                                  "owner"
                                ],
                                "subject": "Quote {reference} accepted: {quote_amount} USD",
                                "body": "{contact.name} ({contact.phone}) accepted.\n\n{answers}\n\n{desk_link}",
                                "attach_files": false
                              }
                            ]
                          }
                        ],
                        "publish": [
                          "quote"
                        ]
                      }
                    }
                  ],
                  "this_number": {
                    "enabled": true,
                    "forms": [
                      "meter_reading"
                    ],
                    "lists": [
                      "products"
                    ],
                    "connections": [
                      "erp"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/settings": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getSubmitSettings",
        "summary": "Submit-Info settings: the switch, the config and the public code",
        "description": "Scope: `submissions:manage`. `enabled` says whether Submit-Info is switched on for the number (words, links and automations work only then; everything can be set up while it is off). `config` holds every setting with its value: the default reference prefix, the menu and status words, where e-mails go, the time zone, the look of the web pages, shared inbox views and the retention time. `code` is the number's public code in every form and inbox address.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The settings.",
            "schema": {
              "$ref": "#/definitions/SubmitSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s1set",
                "enabled": true,
                "config": {
                  "business_name": "",
                  "default_prefix": "SI",
                  "menu_words": [
                    "form",
                    "forms",
                    "report",
                    "submit"
                  ],
                  "menu_text": "What would you like to send us?",
                  "status_words": [
                    "status"
                  ],
                  "other_words_limit": 10,
                  "notify_email": "",
                  "timezone": "",
                  "brand": {
                    "color": "#2DAE5C",
                    "background": "#FFFFFF",
                    "hide_branding": false
                  },
                  "views": [
                    {
                      "key": "urgent",
                      "name": "Urgent",
                      "filter": {
                        "priority": [
                          "urgent"
                        ],
                        "status_kind": [
                          "open"
                        ]
                      }
                    }
                  ],
                  "retention_days": 0
                },
                "code": "k3xbq9rtzp2mwv7",
                "links": {
                  "forms": "https://www.app2email.com/form/k3xbq9rtzp2mwv7",
                  "desk": "https://www.app2email.com/desk/k3xbq9rtzp2mwv7",
                  "wa_me": "https://wa.me/4976659348270"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "updateSubmitSettings",
        "summary": "Switch Submit-Info on or off and change its settings",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Send `enabled`, `config`, or both (400 `nothing_to_change` with neither). `config` is partial: only the keys you send change. A section such as `brand` is merged key by key; a list such as `menu_words` or `views` replaces what is stored. The result is checked as a whole (400 `invalid_settings` with the problems in `error.details`; nothing is saved then). Switching on makes the forms' words and links answer; a form still needs POST /submit/forms/{key}/publish to open inside WhatsApp.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitSettingsUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved: the settings as they are now.",
            "schema": {
              "$ref": "#/definitions/SubmitSettingsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s1set",
                "enabled": true,
                "config": {
                  "business_name": "",
                  "default_prefix": "SI",
                  "menu_words": [
                    "form",
                    "forms",
                    "report",
                    "submit"
                  ],
                  "menu_text": "What would you like to send us?",
                  "status_words": [
                    "status"
                  ],
                  "other_words_limit": 10,
                  "notify_email": "",
                  "timezone": "",
                  "brand": {
                    "color": "#2DAE5C",
                    "background": "#FFFFFF",
                    "hide_branding": false
                  },
                  "views": [
                    {
                      "key": "urgent",
                      "name": "Urgent",
                      "filter": {
                        "priority": [
                          "urgent"
                        ],
                        "status_kind": [
                          "open"
                        ]
                      }
                    }
                  ],
                  "retention_days": 0
                },
                "code": "k3xbq9rtzp2mwv7",
                "links": {
                  "forms": "https://www.app2email.com/form/k3xbq9rtzp2mwv7",
                  "desk": "https://www.app2email.com/desk/k3xbq9rtzp2mwv7",
                  "wa_me": "https://wa.me/4976659348270"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/setup": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "applySubmitSetup",
        "summary": "Apply or dry-run a whole setup: forms, lists, automations",
        "description": "Scope: `submissions:manage`. A sandbox key may only make a dry run. The one call that builds a solution: settings, lists, connections, forms and automations in one document (the SubmitSetup schema; GET /submit/guide has complete examples). Always send it with `dry_run` true first: the answer lists every problem with its path and a fix, and writes nothing. When `problems` is empty, send it again without `dry_run`. What exists under the same key is replaced (lists, connections, forms by `key`; automations by `name` within a form); everything else is left alone. With any problem nothing is written at all: 400 `invalid_setup` with the problems in `error.details`. `publish` names the forms to publish to WhatsApp after a clean apply; otherwise call POST /submit/forms/{key}/publish. A form that cannot be published does not undo the rest: the answer is still 200, `applied.published` names the forms that went live and `problems` says why another did not. `preset` in place of the parts installs a ready-made solution. If a save fails half-way (rare) the answer is 500 with `error.details.applied`: send the same document again, every part replaces what is there.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitSetup"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Checked (dry run) or applied.",
            "schema": {
              "$ref": "#/definitions/SubmitSetupResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s2stp",
                "dry_run": true,
                "note": "Dry run: no problem found, nothing was saved. Send the same document without dry_run to apply it.",
                "applied": {
                  "lists": [
                    "products"
                  ],
                  "connections": [
                    "erp"
                  ],
                  "forms": [
                    "quote"
                  ],
                  "automations": [
                    "Price a quote request in the ERP",
                    "Tell the owner when a quote is accepted"
                  ],
                  "published": []
                },
                "problems": []
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/presets": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listSubmitPresets",
        "summary": "The ready-made setups (presets), or one complete preset",
        "description": "Scope: `submissions:manage`. The presets, each with key, name, description and category (Customers or Field staff): quote, application, documents, meter_reading, problem_report, contact_request, complaint, maintenance, feedback, job_completed, proof_of_delivery, expense, inspection, incident, leave_request. Each is a complete setup document (a form with stages, the lists it needs and the automations that go with it). `?key=` returns that one as `preset`: read it, change what you need and send it to POST /submit/setup; or send `{\"preset\": \"<key>\"}` there to install it as it is. An unknown key answers 400 `invalid_setup`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "description": "One preset's key: the answer then has key and preset, the complete setup document.",
            "type": "string",
            "x-example": "quote"
          }
        ],
        "responses": {
          "200": {
            "description": "The presets.",
            "schema": {
              "$ref": "#/definitions/SubmitPresetsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "p1pre",
                "presets": [
                  {
                    "key": "quote",
                    "name": "Quote request",
                    "description": "What is needed, quantity, photos and address. Staff enter the amount; the customer accepts or declines with a button.",
                    "category": "Customers"
                  },
                  {
                    "key": "meter_reading",
                    "name": "Meter reading",
                    "description": "Meter number, reading and a photo. The usage since the last reading is calculated; odd readings are queried.",
                    "category": "Customers"
                  },
                  {
                    "key": "job_completed",
                    "name": "Job completed",
                    "description": "Field staff log a finished job: the job from a list, work done, parts, hours, photos and the location.",
                    "category": "Field staff"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/forms": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listForms",
        "summary": "The forms of the number",
        "description": "Scope: `submissions:manage`. Every form with its key, name, whether it is enabled, archived and published, whether the working copy differs from the published version (`changed`), its state on WhatsApp, its links and how many submissions it has. Definitions are left out: GET /submit/forms/{key} has one form's definition and fields.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The forms.",
            "schema": {
              "$ref": "#/definitions/SubmitFormsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f1lst",
                "forms": [
                  {
                    "id": 7,
                    "key": "meter_reading",
                    "name": "Meter reading",
                    "enabled": true,
                    "archived": false,
                    "position": 0,
                    "published": {
                      "hash": "3f9a1c0b7d2e",
                      "published_at": "2026-11-13T04:00:00.000Z"
                    },
                    "changed": false,
                    "flow": {
                      "id": "1234567890123456",
                      "status": "PUBLISHED",
                      "validation_errors": [],
                      "checked_at": "2026-11-13T04:00:00.000Z",
                      "last_error": "",
                      "can_send": true
                    },
                    "links": {
                      "web": "https://www.app2email.com/form/k3xbq9rtzp2mwv7/meter_reading",
                      "wa_me": "https://wa.me/4976659348270?text=meter",
                      "words": [
                        "meter",
                        "reading"
                      ]
                    },
                    "counts": {
                      "open": 12,
                      "total": 148
                    },
                    "created": "2026-11-12T22:10:00.000Z",
                    "updated": "2026-11-13T04:00:00.000Z"
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "createForm",
        "summary": "Create a form from a definition or a preset",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Send `name` and `definition` (the SubmitFormDefinition schema explains every key; a minimal form is a title and one step with one field). `name` alone makes a starter form with one question to change. `preset` installs a ready-made solution instead: its form with the lists and automations that belong to it (`applied` in the answer names them). The definition is checked as a whole: 400 `invalid_form` lists every problem with its path (`definition.steps[0].fields[1].label`) and a fix, and nothing is saved. The answer is the form with its normalized definition and its links. The web page works at once; to open the form inside WhatsApp call POST /submit/forms/{key}/publish next. A number has at most 100 forms.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitFormCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/SubmitFormResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f2crt",
                "form": {
                  "id": 7,
                  "key": "meter_reading",
                  "name": "Meter reading",
                  "enabled": true,
                  "archived": false,
                  "position": 0,
                  "published": null,
                  "changed": false,
                  "flow": {
                    "id": "",
                    "status": "",
                    "validation_errors": [],
                    "checked_at": "",
                    "last_error": "",
                    "can_send": false
                  },
                  "links": {
                    "web": "https://www.app2email.com/form/k3xbq9rtzp2mwv7/meter_reading",
                    "wa_me": "https://wa.me/4976659348270?text=meter",
                    "words": [
                      "meter",
                      "reading"
                    ]
                  },
                  "counts": {
                    "open": 0,
                    "total": 0
                  },
                  "created": "2026-11-12T22:10:00.000Z",
                  "updated": "2026-11-13T04:00:00.000Z",
                  "definition": {
                    "title": "Meter reading",
                    "description": "Send us this month's reading.",
                    "prefix": "MR",
                    "steps": [
                      {
                        "key": "reading",
                        "title": "Your reading",
                        "text": "",
                        "show_if": null,
                        "fields": [
                          {
                            "key": "meter_no",
                            "type": "text",
                            "label": "Meter number",
                            "help": "On the front of the meter",
                            "required": true,
                            "default": "{contact.meter_no}",
                            "max_length": 20
                          },
                          {
                            "key": "reading",
                            "type": "number",
                            "label": "Meter reading",
                            "required": true,
                            "min": 0,
                            "max": 999999,
                            "decimals": 0,
                            "unit": "kWh"
                          },
                          {
                            "key": "photo",
                            "type": "photo",
                            "label": "Photo of the meter",
                            "required": true,
                            "max_files": 1,
                            "source": "camera"
                          },
                          {
                            "key": "moving",
                            "type": "yesno",
                            "label": "Are you moving out?",
                            "required": true
                          },
                          {
                            "key": "billing_ref",
                            "type": "text",
                            "label": "Billing reference",
                            "internal": true
                          }
                        ]
                      },
                      {
                        "key": "move",
                        "title": "Your move",
                        "text": "We will close the account on that day.",
                        "show_if": {
                          "field": "moving",
                          "equals": true
                        },
                        "fields": [
                          {
                            "key": "move_date",
                            "type": "date",
                            "label": "Moving date",
                            "required": true,
                            "min_days": -30,
                            "max_days": 90
                          },
                          {
                            "key": "new_address",
                            "type": "textarea",
                            "label": "New address for the final bill",
                            "required": false,
                            "max_length": 300
                          }
                        ]
                      }
                    ],
                    "stages": [
                      {
                        "key": "received",
                        "name": "Received",
                        "kind": "open",
                        "color": "blue",
                        "set_by": [],
                        "require_note": false,
                        "message": ""
                      },
                      {
                        "key": "queried",
                        "name": "Queried",
                        "kind": "open",
                        "color": "amber",
                        "set_by": [],
                        "require_note": true,
                        "message": "We have a question about your reading {reference}: {note}"
                      },
                      {
                        "key": "checked",
                        "name": "Checked",
                        "kind": "done",
                        "color": "green",
                        "set_by": [
                          "manager"
                        ],
                        "require_note": false,
                        "message": "Thanks {contact.name}, your reading of {reading} kWh is recorded."
                      }
                    ],
                    "who": {
                      "mode": "anyone",
                      "numbers": [],
                      "tag": ""
                    },
                    "trigger": {
                      "words": [
                        "meter",
                        "reading"
                      ],
                      "header": "",
                      "body": "Tap the button to send your reading.",
                      "button": "Open form",
                      "footer": ""
                    },
                    "after": {
                      "review_step": true,
                      "reply": "Thanks {contact.name}. We have your {form} - reference {reference}.",
                      "allow_additions": false,
                      "status_page": true
                    },
                    "web": {
                      "enabled": true,
                      "verify": "optional",
                      "ask_email": false,
                      "success_text": ""
                    },
                    "notify": {
                      "email": true,
                      "to": [],
                      "attach_files": true
                    },
                    "calculated": [
                      {
                        "key": "usage",
                        "label": "Usage",
                        "formula": "reading - previous('reading')",
                        "unit": "kWh",
                        "decimals": 0
                      }
                    ],
                    "retention_days": 0
                  },
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/forms/{key}": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getForm",
        "summary": "One form: definition, fields, links and WhatsApp state",
        "description": "Scope: `submissions:manage`. The form's working definition with every default filled in, `fields` (every field and calculated value as a column: the keys to read in a submission's answers and extra), `links` (the web page, the wa.me link, the words), `published` and `changed` (does WhatsApp show the latest version?) and `flow` (Meta's status and complaints). Read it before changing a definition: PUT takes the whole definition back.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The form's key (GET /submit/forms).",
            "type": "string",
            "x-example": "meter_reading"
          }
        ],
        "responses": {
          "200": {
            "description": "The form.",
            "schema": {
              "$ref": "#/definitions/SubmitFormResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f3get",
                "form": {
                  "id": 7,
                  "key": "meter_reading",
                  "name": "Meter reading",
                  "enabled": true,
                  "archived": false,
                  "position": 0,
                  "published": {
                    "hash": "3f9a1c0b7d2e",
                    "published_at": "2026-11-13T04:00:00.000Z"
                  },
                  "changed": false,
                  "flow": {
                    "id": "1234567890123456",
                    "status": "PUBLISHED",
                    "validation_errors": [],
                    "checked_at": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "can_send": true
                  },
                  "links": {
                    "web": "https://www.app2email.com/form/k3xbq9rtzp2mwv7/meter_reading",
                    "wa_me": "https://wa.me/4976659348270?text=meter",
                    "words": [
                      "meter",
                      "reading"
                    ]
                  },
                  "counts": {
                    "open": 12,
                    "total": 148
                  },
                  "created": "2026-11-12T22:10:00.000Z",
                  "updated": "2026-11-13T04:00:00.000Z",
                  "definition": {
                    "title": "Meter reading",
                    "description": "Send us this month's reading.",
                    "prefix": "MR",
                    "steps": [
                      {
                        "key": "reading",
                        "title": "Your reading",
                        "text": "",
                        "show_if": null,
                        "fields": [
                          {
                            "key": "meter_no",
                            "type": "text",
                            "label": "Meter number",
                            "help": "On the front of the meter",
                            "required": true,
                            "default": "{contact.meter_no}",
                            "max_length": 20
                          },
                          {
                            "key": "reading",
                            "type": "number",
                            "label": "Meter reading",
                            "required": true,
                            "min": 0,
                            "max": 999999,
                            "decimals": 0,
                            "unit": "kWh"
                          },
                          {
                            "key": "photo",
                            "type": "photo",
                            "label": "Photo of the meter",
                            "required": true,
                            "max_files": 1,
                            "source": "camera"
                          },
                          {
                            "key": "moving",
                            "type": "yesno",
                            "label": "Are you moving out?",
                            "required": true
                          },
                          {
                            "key": "billing_ref",
                            "type": "text",
                            "label": "Billing reference",
                            "internal": true
                          }
                        ]
                      },
                      {
                        "key": "move",
                        "title": "Your move",
                        "text": "We will close the account on that day.",
                        "show_if": {
                          "field": "moving",
                          "equals": true
                        },
                        "fields": [
                          {
                            "key": "move_date",
                            "type": "date",
                            "label": "Moving date",
                            "required": true,
                            "min_days": -30,
                            "max_days": 90
                          },
                          {
                            "key": "new_address",
                            "type": "textarea",
                            "label": "New address for the final bill",
                            "required": false,
                            "max_length": 300
                          }
                        ]
                      }
                    ],
                    "stages": [
                      {
                        "key": "received",
                        "name": "Received",
                        "kind": "open",
                        "color": "blue",
                        "set_by": [],
                        "require_note": false,
                        "message": ""
                      },
                      {
                        "key": "queried",
                        "name": "Queried",
                        "kind": "open",
                        "color": "amber",
                        "set_by": [],
                        "require_note": true,
                        "message": "We have a question about your reading {reference}: {note}"
                      },
                      {
                        "key": "checked",
                        "name": "Checked",
                        "kind": "done",
                        "color": "green",
                        "set_by": [
                          "manager"
                        ],
                        "require_note": false,
                        "message": "Thanks {contact.name}, your reading of {reading} kWh is recorded."
                      }
                    ],
                    "who": {
                      "mode": "anyone",
                      "numbers": [],
                      "tag": ""
                    },
                    "trigger": {
                      "words": [
                        "meter",
                        "reading"
                      ],
                      "header": "",
                      "body": "Tap the button to send your reading.",
                      "button": "Open form",
                      "footer": ""
                    },
                    "after": {
                      "review_step": true,
                      "reply": "Thanks {contact.name}. We have your {form} - reference {reference}.",
                      "allow_additions": false,
                      "status_page": true
                    },
                    "web": {
                      "enabled": true,
                      "verify": "optional",
                      "ask_email": false,
                      "success_text": ""
                    },
                    "notify": {
                      "email": true,
                      "to": [],
                      "attach_files": true
                    },
                    "calculated": [
                      {
                        "key": "usage",
                        "label": "Usage",
                        "formula": "reading - previous('reading')",
                        "unit": "kWh",
                        "decimals": 0
                      }
                    ],
                    "retention_days": 0
                  },
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "updateForm",
        "summary": "Change a form: name, on or off, archive, definition",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Any of `name`, `enabled`, `archived`, `position`, `definition` (400 `nothing_to_change` with none). A `definition` replaces the whole working copy, so read the form, change it and send all of it back; it is checked as a whole (400 `invalid_form`, nothing saved). The web page follows the saved definition. WhatsApp keeps showing the published version: call POST /submit/forms/{key}/publish to make a changed definition live there. Submissions already made keep their answers; a removed field stays readable in them.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The form's key (GET /submit/forms).",
            "type": "string",
            "x-example": "meter_reading"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitFormUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/SubmitFormResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f4upd",
                "form": {
                  "id": 7,
                  "key": "meter_reading",
                  "name": "Meter reading",
                  "enabled": true,
                  "archived": false,
                  "position": 0,
                  "published": {
                    "hash": "3f9a1c0b7d2e",
                    "published_at": "2026-11-13T04:00:00.000Z"
                  },
                  "changed": true,
                  "flow": {
                    "id": "1234567890123456",
                    "status": "PUBLISHED",
                    "validation_errors": [],
                    "checked_at": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "can_send": true
                  },
                  "links": {
                    "web": "https://www.app2email.com/form/k3xbq9rtzp2mwv7/meter_reading",
                    "wa_me": "https://wa.me/4976659348270?text=meter",
                    "words": [
                      "meter",
                      "reading"
                    ]
                  },
                  "counts": {
                    "open": 12,
                    "total": 148
                  },
                  "created": "2026-11-12T22:10:00.000Z",
                  "updated": "2026-11-13T04:00:00.000Z",
                  "definition": {
                    "title": "Meter reading",
                    "description": "Send us this month's reading.",
                    "prefix": "MR",
                    "steps": [
                      {
                        "key": "reading",
                        "title": "Your reading",
                        "text": "",
                        "show_if": null,
                        "fields": [
                          {
                            "key": "meter_no",
                            "type": "text",
                            "label": "Meter number",
                            "help": "On the front of the meter",
                            "required": true,
                            "default": "{contact.meter_no}",
                            "max_length": 20
                          },
                          {
                            "key": "reading",
                            "type": "number",
                            "label": "Meter reading",
                            "required": true,
                            "min": 0,
                            "max": 999999,
                            "decimals": 0,
                            "unit": "kWh"
                          },
                          {
                            "key": "photo",
                            "type": "photo",
                            "label": "Photo of the meter",
                            "required": true,
                            "max_files": 1,
                            "source": "camera"
                          },
                          {
                            "key": "moving",
                            "type": "yesno",
                            "label": "Are you moving out?",
                            "required": true
                          },
                          {
                            "key": "billing_ref",
                            "type": "text",
                            "label": "Billing reference",
                            "internal": true
                          }
                        ]
                      },
                      {
                        "key": "move",
                        "title": "Your move",
                        "text": "We will close the account on that day.",
                        "show_if": {
                          "field": "moving",
                          "equals": true
                        },
                        "fields": [
                          {
                            "key": "move_date",
                            "type": "date",
                            "label": "Moving date",
                            "required": true,
                            "min_days": -30,
                            "max_days": 90
                          },
                          {
                            "key": "new_address",
                            "type": "textarea",
                            "label": "New address for the final bill",
                            "required": false,
                            "max_length": 300
                          }
                        ]
                      }
                    ],
                    "stages": [
                      {
                        "key": "received",
                        "name": "Received",
                        "kind": "open",
                        "color": "blue",
                        "set_by": [],
                        "require_note": false,
                        "message": ""
                      },
                      {
                        "key": "queried",
                        "name": "Queried",
                        "kind": "open",
                        "color": "amber",
                        "set_by": [],
                        "require_note": true,
                        "message": "We have a question about your reading {reference}: {note}"
                      },
                      {
                        "key": "checked",
                        "name": "Checked",
                        "kind": "done",
                        "color": "green",
                        "set_by": [
                          "manager"
                        ],
                        "require_note": false,
                        "message": "Thanks {contact.name}, your reading of {reading} kWh is recorded."
                      }
                    ],
                    "who": {
                      "mode": "anyone",
                      "numbers": [],
                      "tag": ""
                    },
                    "trigger": {
                      "words": [
                        "meter",
                        "reading"
                      ],
                      "header": "",
                      "body": "Tap the button to send your reading.",
                      "button": "Open form",
                      "footer": ""
                    },
                    "after": {
                      "review_step": true,
                      "reply": "Thanks {contact.name}. We have your {form} - reference {reference}.",
                      "allow_additions": false,
                      "status_page": true
                    },
                    "web": {
                      "enabled": true,
                      "verify": "optional",
                      "ask_email": false,
                      "success_text": ""
                    },
                    "notify": {
                      "email": true,
                      "to": [],
                      "attach_files": true
                    },
                    "calculated": [
                      {
                        "key": "usage",
                        "label": "Usage",
                        "formula": "reading - previous('reading')",
                        "unit": "kWh",
                        "decimals": 0
                      }
                    ],
                    "retention_days": 0
                  },
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "deleteForm",
        "summary": "Delete a form (archived when it has submissions)",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. A form without submissions is deleted, and its WhatsApp version is retired: form messages already sent stop opening. A form that has submissions is never deleted, because they belong to it: it is archived instead (no longer offered, its submissions stay) and the answer says `deleted` false, `archived` true with a note. PUT /submit/forms/{key} `{\"archived\": false}` brings an archived form back.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The form's key (GET /submit/forms).",
            "type": "string",
            "x-example": "meter_reading"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted or archived.",
            "schema": {
              "$ref": "#/definitions/SubmitDeletedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f5del",
                "deleted": true,
                "archived": false,
                "key": "meter_reading"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/forms/{key}/publish": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "publishForm",
        "summary": "Publish a form to WhatsApp",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Builds the WhatsApp form from the saved definition, uploads it to Meta and publishes it. From then on the form's words, POST /submit/forms/{key}/send and the menu open it inside WhatsApp. Call it after creating a form and after every change of its definition. 400 `invalid_form` when the definition cannot be built into a WhatsApp form (the message says what to change). 409 `form_not_published` when the form is archived, the number's encryption key is not accepted by WhatsApp yet, or WhatsApp found problems in the generated form (`error.details.validation_errors` has them). 502 `whatsapp_flow_failed` when WhatsApp refused a call: try again in a minute. People who still have an older message keep the version it was sent with. A form that is not published still works through its web link.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The form's key (GET /submit/forms).",
            "type": "string",
            "x-example": "meter_reading"
          }
        ],
        "responses": {
          "200": {
            "description": "Published.",
            "schema": {
              "$ref": "#/definitions/SubmitFormResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f6pub",
                "form": {
                  "id": 7,
                  "key": "meter_reading",
                  "name": "Meter reading",
                  "enabled": true,
                  "archived": false,
                  "position": 0,
                  "published": {
                    "hash": "3f9a1c0b7d2e",
                    "published_at": "2026-11-13T04:00:00.000Z"
                  },
                  "changed": false,
                  "flow": {
                    "id": "1234567890123456",
                    "status": "PUBLISHED",
                    "validation_errors": [],
                    "checked_at": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "can_send": true
                  },
                  "links": {
                    "web": "https://www.app2email.com/form/k3xbq9rtzp2mwv7/meter_reading",
                    "wa_me": "https://wa.me/4976659348270?text=meter",
                    "words": [
                      "meter",
                      "reading"
                    ]
                  },
                  "counts": {
                    "open": 12,
                    "total": 148
                  },
                  "created": "2026-11-12T22:10:00.000Z",
                  "updated": "2026-11-13T04:00:00.000Z",
                  "definition": {
                    "title": "Meter reading",
                    "description": "Send us this month's reading.",
                    "prefix": "MR",
                    "steps": [
                      {
                        "key": "reading",
                        "title": "Your reading",
                        "text": "",
                        "show_if": null,
                        "fields": [
                          {
                            "key": "meter_no",
                            "type": "text",
                            "label": "Meter number",
                            "help": "On the front of the meter",
                            "required": true,
                            "default": "{contact.meter_no}",
                            "max_length": 20
                          },
                          {
                            "key": "reading",
                            "type": "number",
                            "label": "Meter reading",
                            "required": true,
                            "min": 0,
                            "max": 999999,
                            "decimals": 0,
                            "unit": "kWh"
                          },
                          {
                            "key": "photo",
                            "type": "photo",
                            "label": "Photo of the meter",
                            "required": true,
                            "max_files": 1,
                            "source": "camera"
                          },
                          {
                            "key": "moving",
                            "type": "yesno",
                            "label": "Are you moving out?",
                            "required": true
                          },
                          {
                            "key": "billing_ref",
                            "type": "text",
                            "label": "Billing reference",
                            "internal": true
                          }
                        ]
                      },
                      {
                        "key": "move",
                        "title": "Your move",
                        "text": "We will close the account on that day.",
                        "show_if": {
                          "field": "moving",
                          "equals": true
                        },
                        "fields": [
                          {
                            "key": "move_date",
                            "type": "date",
                            "label": "Moving date",
                            "required": true,
                            "min_days": -30,
                            "max_days": 90
                          },
                          {
                            "key": "new_address",
                            "type": "textarea",
                            "label": "New address for the final bill",
                            "required": false,
                            "max_length": 300
                          }
                        ]
                      }
                    ],
                    "stages": [
                      {
                        "key": "received",
                        "name": "Received",
                        "kind": "open",
                        "color": "blue",
                        "set_by": [],
                        "require_note": false,
                        "message": ""
                      },
                      {
                        "key": "queried",
                        "name": "Queried",
                        "kind": "open",
                        "color": "amber",
                        "set_by": [],
                        "require_note": true,
                        "message": "We have a question about your reading {reference}: {note}"
                      },
                      {
                        "key": "checked",
                        "name": "Checked",
                        "kind": "done",
                        "color": "green",
                        "set_by": [
                          "manager"
                        ],
                        "require_note": false,
                        "message": "Thanks {contact.name}, your reading of {reading} kWh is recorded."
                      }
                    ],
                    "who": {
                      "mode": "anyone",
                      "numbers": [],
                      "tag": ""
                    },
                    "trigger": {
                      "words": [
                        "meter",
                        "reading"
                      ],
                      "header": "",
                      "body": "Tap the button to send your reading.",
                      "button": "Open form",
                      "footer": ""
                    },
                    "after": {
                      "review_step": true,
                      "reply": "Thanks {contact.name}. We have your {form} - reference {reference}.",
                      "allow_additions": false,
                      "status_page": true
                    },
                    "web": {
                      "enabled": true,
                      "verify": "optional",
                      "ask_email": false,
                      "success_text": ""
                    },
                    "notify": {
                      "email": true,
                      "to": [],
                      "attach_files": true
                    },
                    "calculated": [
                      {
                        "key": "usage",
                        "label": "Usage",
                        "formula": "reading - previous('reading')",
                        "unit": "kWh",
                        "decimals": 0
                      }
                    ],
                    "retention_days": 0
                  },
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ]
                },
                "note": "Published. The form's words and its send route now open this version on WhatsApp."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/forms/{key}/send": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "sendForm",
        "summary": "Send a form to a contact, with values filled in",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Sends the form to one contact, with `prefill` values you already know (a job number, an account, the documents wanted). The WhatsApp form goes out when the form is published and the contact wrote to the number in the last 24 hours; a form that is not published goes out as a message with a button to the contact's personal web link. Outside the 24 hour window, or when a form message went to the contact less than 2 minutes ago, nothing is sent: the answer is still 200 with `sent` false and `note` saying why. `link` is always returned: when nothing was sent, send it yourself, for example in an approved template. `link_only` true sends nothing and just returns the link. `parent` makes the new submission a follow-up of an earlier one. The answers arrive as `submission.created`. 403 `submit_not_enabled` while Submit-Info is switched off; 409 `form_not_published` when the form is switched off or archived; 403 `recipient_opted_out` when the contact asked not to be messaged.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The form's key (GET /submit/forms).",
            "type": "string",
            "x-example": "meter_reading"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitFormSendRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent, or the link to send.",
            "schema": {
              "$ref": "#/definitions/SubmitFormSendResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "f7snd",
                "sent": true,
                "sent_flow": true,
                "link": "https://www.app2email.com/form/k3xbq9rtzp2mwv7/meter_reading?t=si1.eyJuIjoxMzJ9.c2FtcGxl",
                "session_id": 518,
                "to": "61412345678",
                "note": "Sent as a WhatsApp form."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/lists": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listSubmitLists",
        "summary": "The choice lists (sites, jobs, price lists)",
        "description": "Scope: `submissions:manage`. Lists hold choices outside the forms. A select field with `list` set to a list's key shows its items, read fresh each time the form opens, so a list can change every day without publishing anything. Formulas read the other columns of an item: `lookup('products', product, 'price')`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The lists.",
            "schema": {
              "$ref": "#/definitions/SubmitListsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "l1lst",
                "lists": [
                  {
                    "key": "products",
                    "name": "Products",
                    "items": [
                      {
                        "id": "pump-s",
                        "title": "Pump, small",
                        "description": "Up to 40 l/min",
                        "price": 240
                      },
                      {
                        "id": "pump-l",
                        "title": "Pump, large",
                        "description": "Up to 120 l/min",
                        "price": 610
                      }
                    ],
                    "count": 2,
                    "updated": "2026-11-13T04:00:00.000Z"
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/lists/{key}": {
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "setSubmitList",
        "summary": "Create a list or replace its items",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Makes the list when the key is new; otherwise replaces its name and ALL its items (send the full list every time, for example from a nightly sync of jobs or prices). Each item needs a unique `id` (stored as the answer) and a `title` (what people see; left out, the id); any other key is a column for formulas. A plain text instead of an object is an item whose id and title are that text. Up to 1,000 items and 200 KB; a form shows the first 200. Forms pick the change up at once: no publish is needed. A number has at most 50 lists.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The list's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "products"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitListSetRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/SubmitListResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "l2set",
                "list": {
                  "key": "products",
                  "name": "Products",
                  "items": [
                    {
                      "id": "pump-s",
                      "title": "Pump, small",
                      "description": "Up to 40 l/min",
                      "price": 240
                    },
                    {
                      "id": "pump-l",
                      "title": "Pump, large",
                      "description": "Up to 120 l/min",
                      "price": 610
                    }
                  ],
                  "count": 2,
                  "updated": "2026-11-13T04:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "deleteSubmitList",
        "summary": "Delete a list",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. A select field that still names the list then shows one line, Nothing to choose, until the list is made again or the question is changed. `used_by` in the answer names those forms.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The list's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "products"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/SubmitDeletedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "l3del",
                "deleted": true,
                "key": "products",
                "used_by": [
                  "quote"
                ],
                "note": "Deleted. The forms in used_by still name this list: their question now shows \"Nothing to choose\" until the list is made again or the question is changed."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/submissions": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listSubmissions",
        "summary": "The submissions, filtered and paged (JSON or CSV)",
        "description": "Scope: `submissions:manage`. Latest change first; deleted ones are left out. Filter by form, stage (`status`, or `status_kind` open / done / cancelled), assignee, priority, tag, channel, contact, a search text, the creation time or the parent. `form`, `status`, `status_kind`, `assignee`, `priority`, `tag` and `channel` take several values with commas. To keep another system in step, poll with `updated_after` set to the largest `updated` you have seen and `sort=updated_asc`, or use the `submission.*` webhook events and skip polling. Page with `next_cursor` (the same filter and sort). `format=csv` (or the header `Accept: text/csv`) answers the same page as CSV, one column per field when one `form` is given; the next cursor is then in the header `X-Next-Cursor`. Lists leave out files and activity: GET /submit/submissions/{id} has them. A filter value that cannot be read answers 400 `invalid_submission` and names it; an unknown `parent` answers an empty list.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "form",
            "in": "query",
            "required": false,
            "description": "Only this form (its key). Several: keys with commas.",
            "type": "string",
            "x-example": "meter_reading"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only these stages: stage keys of the form, with commas.",
            "type": "string",
            "x-example": "received"
          },
          {
            "name": "status_kind",
            "in": "query",
            "required": false,
            "description": "Only stages of this kind: open, done or cancelled (several with commas).",
            "type": "string",
            "x-example": "open"
          },
          {
            "name": "assignee",
            "in": "query",
            "required": false,
            "description": "Only what these members hold: member ids with commas. 0 = not assigned.",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "description": "low, normal, high or urgent; several with commas.",
            "type": "string",
            "x-example": "high,urgent"
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only submissions with one of these tags (commas).",
            "type": "string",
            "x-example": "north"
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "whatsapp, web, api or staff; several with commas.",
            "type": "string",
            "x-example": "whatsapp"
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "Only this person's (number with country code, or business-scoped user id).",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "The reference, a name or an answer contains this text.",
            "type": "string",
            "x-example": "A-1182"
          },
          {
            "name": "created_from",
            "in": "query",
            "required": false,
            "description": "Created on or after this day (YYYY-MM-DD) or ISO 8601 time.",
            "type": "string",
            "x-example": "2026-11-01"
          },
          {
            "name": "created_to",
            "in": "query",
            "required": false,
            "description": "Created up to and including this day (YYYY-MM-DD), or before this ISO 8601 time.",
            "type": "string",
            "x-example": "2026-11-30"
          },
          {
            "name": "updated_after",
            "in": "query",
            "required": false,
            "description": "Changed after this ISO 8601 time: for syncing.",
            "type": "string",
            "x-example": "2026-11-13T04:00:00Z"
          },
          {
            "name": "parent",
            "in": "query",
            "required": false,
            "description": "Only the follow-ups of this submission (id or reference).",
            "type": "string",
            "x-example": "QR-4HT9XC"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "updated (default), created, due or priority; add _asc for the opposite order.",
            "type": "string",
            "enum": [
              "updated",
              "created",
              "due",
              "priority",
              "updated_asc",
              "created_asc",
              "due_asc",
              "priority_asc"
            ],
            "default": "updated"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "csv: a text/csv answer.",
            "type": "string",
            "enum": [
              "json",
              "csv"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The submissions.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s1lst",
                "submissions": [
                  {
                    "id": 4182,
                    "reference": "MR-7Q3M2A",
                    "form": {
                      "key": "meter_reading",
                      "name": "Meter reading"
                    },
                    "channel": "whatsapp",
                    "status": "received",
                    "status_name": "Received",
                    "status_kind": "open",
                    "status_color": "blue",
                    "priority": "normal",
                    "tags": [
                      "north"
                    ],
                    "due": null,
                    "assignee": {
                      "id": 12,
                      "name": "Sam"
                    },
                    "contact": {
                      "identity": "61412345678",
                      "name": "John Smith",
                      "phone": "61412345678",
                      "email": "",
                      "verified": true
                    },
                    "conversation_id": 8762,
                    "answers": {
                      "meter_no": "A-1182",
                      "reading": 48213,
                      "photo": [
                        9917
                      ],
                      "moving": false
                    },
                    "extra": {
                      "usage": 312
                    },
                    "location": null,
                    "parent": null,
                    "summary": "A-1182 · 48213",
                    "files_count": 1,
                    "files_pending": 0,
                    "unread": true,
                    "link": "https://www.app2email.com/s/4mXk9QpL2vTz8RwY3nBc6HdJ5sFg7Ka1",
                    "created": "2026-11-13T04:00:00.000Z",
                    "updated": "2026-11-13T04:00:00.000Z",
                    "status_changed": "2026-11-13T04:00:00.000Z",
                    "closed": null
                  }
                ],
                "count": 1
              }
            },
            "headers": {
              "X-Next-Cursor": {
                "type": "string",
                "description": "CSV only: the cursor of the next page. Left out on the last page."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "produces": [
          "text/csv",
          "application/json"
        ]
      },
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "createSubmission",
        "summary": "Create a submission from data you already hold",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. For a system that already has the answers (a web shop, a call centre, an import). `form` is the form's key; `answers` are checked exactly like a customer's (required fields, ranges, choice ids: 400 `invalid_submission` names each field in `error.details`); `extra` fills internal fields; `files` attach base64 files to photo and document fields (up to 20 in one request, 10 MB each); `assignee` and `location` are optional. The submission gets a reference, starts in the form's first stage (or `status`), has channel `api`, and runs the form's automations like any other. No message is sent to the contact by this call itself; the form's automations may send one. `submission.created` is sent. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmissionCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/SubmissionResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s2crt",
                "submission": {
                  "id": 4182,
                  "reference": "MR-7Q3M2A",
                  "form": {
                    "key": "meter_reading",
                    "name": "Meter reading"
                  },
                  "channel": "api",
                  "status": "received",
                  "status_name": "Received",
                  "status_kind": "open",
                  "status_color": "blue",
                  "priority": "normal",
                  "tags": [
                    "north"
                  ],
                  "due": null,
                  "assignee": null,
                  "contact": {
                    "identity": "61412345678",
                    "name": "John Smith",
                    "phone": "61412345678",
                    "email": "",
                    "verified": true
                  },
                  "conversation_id": 8762,
                  "answers": {
                    "meter_no": "A-1182",
                    "reading": 48213,
                    "photo": [
                      9917
                    ],
                    "moving": false
                  },
                  "extra": {
                    "usage": 312,
                    "billing_ref": "R-88231"
                  },
                  "location": null,
                  "parent": null,
                  "summary": "A-1182 · 48213",
                  "files_count": 1,
                  "files_pending": 0,
                  "unread": true,
                  "link": "https://www.app2email.com/s/4mXk9QpL2vTz8RwY3nBc6HdJ5sFg7Ka1",
                  "created": "2026-11-13T04:00:00.000Z",
                  "updated": "2026-11-13T04:00:00.000Z",
                  "status_changed": "2026-11-13T04:00:00.000Z",
                  "closed": null,
                  "files": [
                    {
                      "id": 9917,
                      "field": "photo",
                      "name": "meter.jpg",
                      "mime": "image/jpeg",
                      "size": 281733,
                      "state": "stored",
                      "source": "api",
                      "url": "https://api.app2email.com/submit/file/c2FtcGxlLWZpbGUtbGluay1ub3QtcmVhbA",
                      "created": "2026-11-13T04:00:00.000Z"
                    }
                  ],
                  "events": [
                    {
                      "id": 60411,
                      "kind": "created",
                      "actor": {
                        "kind": "api",
                        "id": 3,
                        "name": "API key Billing sync"
                      },
                      "text": "",
                      "data": {},
                      "public": false,
                      "created": "2026-11-13T04:00:00.000Z"
                    }
                  ],
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ],
                  "stages": [
                    {
                      "key": "received",
                      "name": "Received",
                      "kind": "open",
                      "color": "blue",
                      "set_by": [],
                      "require_note": false
                    },
                    {
                      "key": "queried",
                      "name": "Queried",
                      "kind": "open",
                      "color": "amber",
                      "set_by": [],
                      "require_note": true
                    },
                    {
                      "key": "checked",
                      "name": "Checked",
                      "kind": "done",
                      "color": "green",
                      "set_by": [
                        "manager"
                      ],
                      "require_note": false
                    }
                  ],
                  "actions": [
                    {
                      "id": 31,
                      "label": "Send to billing"
                    }
                  ],
                  "buttons": []
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/submissions/{id}": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getSubmission",
        "summary": "One submission with files, activity and what can be done",
        "description": "Scope: `submissions:manage`. By id or by reference. Everything about it: the answers and `extra`, `files` (each `url` fetches the bytes without a key for 7 days), `events` (the activity list: who did what, every note, reply and automation step), `fields` (how to label each answer), `stages` (where it can move, with `require_note`), `actions` (the manual automations to run with POST /submit/submissions/{id}/run) and `buttons` (sent to the submitter, not pressed yet). A deleted submission answers 404.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          }
        ],
        "responses": {
          "200": {
            "description": "The submission.",
            "schema": {
              "$ref": "#/definitions/SubmissionResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s3get",
                "submission": {
                  "id": 4182,
                  "reference": "MR-7Q3M2A",
                  "form": {
                    "key": "meter_reading",
                    "name": "Meter reading"
                  },
                  "channel": "whatsapp",
                  "status": "received",
                  "status_name": "Received",
                  "status_kind": "open",
                  "status_color": "blue",
                  "priority": "normal",
                  "tags": [
                    "north"
                  ],
                  "due": null,
                  "assignee": {
                    "id": 12,
                    "name": "Sam"
                  },
                  "contact": {
                    "identity": "61412345678",
                    "name": "John Smith",
                    "phone": "61412345678",
                    "email": "",
                    "verified": true
                  },
                  "conversation_id": 8762,
                  "answers": {
                    "meter_no": "A-1182",
                    "reading": 48213,
                    "photo": [
                      9917
                    ],
                    "moving": false
                  },
                  "extra": {
                    "usage": 312
                  },
                  "location": null,
                  "parent": null,
                  "summary": "A-1182 · 48213",
                  "files_count": 1,
                  "files_pending": 0,
                  "unread": true,
                  "link": "https://www.app2email.com/s/4mXk9QpL2vTz8RwY3nBc6HdJ5sFg7Ka1",
                  "created": "2026-11-13T04:00:00.000Z",
                  "updated": "2026-11-13T04:00:00.000Z",
                  "status_changed": "2026-11-13T04:00:00.000Z",
                  "closed": null,
                  "files": [
                    {
                      "id": 9917,
                      "field": "photo",
                      "name": "IMG_5237.jpg",
                      "mime": "image/jpeg",
                      "size": 281733,
                      "state": "stored",
                      "source": "flow",
                      "url": "https://api.app2email.com/submit/file/c2FtcGxlLWZpbGUtbGluay1ub3QtcmVhbA",
                      "created": "2026-11-13T04:00:00.000Z"
                    }
                  ],
                  "events": [
                    {
                      "id": 60411,
                      "kind": "created",
                      "actor": {
                        "kind": "contact",
                        "id": 0,
                        "name": "John Smith"
                      },
                      "text": "",
                      "data": {},
                      "public": true,
                      "created": "2026-11-13T04:00:00.000Z"
                    }
                  ],
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ],
                  "stages": [
                    {
                      "key": "received",
                      "name": "Received",
                      "kind": "open",
                      "color": "blue",
                      "set_by": [],
                      "require_note": false
                    },
                    {
                      "key": "queried",
                      "name": "Queried",
                      "kind": "open",
                      "color": "amber",
                      "set_by": [],
                      "require_note": true
                    },
                    {
                      "key": "checked",
                      "name": "Checked",
                      "kind": "done",
                      "color": "green",
                      "set_by": [
                        "manager"
                      ],
                      "require_note": false
                    }
                  ],
                  "actions": [
                    {
                      "id": 31,
                      "label": "Send to billing"
                    }
                  ],
                  "buttons": []
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "updateSubmission",
        "summary": "Change a submission: stage, assignee, tags, answers",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Any of: `status` (a stage key; with `note` when the stage has `require_note`, else 409 `stage_not_allowed`), `priority`, `assignee` (a member id; 0 or null = nobody), `due` (null takes it off), `tags` / `tags_add` / `tags_remove`, `answers` and `extra` (only the keys given change, null removes one; calculated values are worked out again) and `location`. A `note` without `status` is written as an internal note. 400 `nothing_to_change` when the body names none of them; `changed` false when the submission already had these values. Each change is written to the activity list under the key's name. Moving to a stage sends that stage's `message` to the submitter, when it has one. Events: `submission.status_changed`, `submission.assigned`, `submission.updated`, `submission.note_added`, one per kind of change; the form's automations run on them.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmissionUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/SubmissionResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s4upd",
                "changed": true,
                "submission": {
                  "id": 4182,
                  "reference": "MR-7Q3M2A",
                  "form": {
                    "key": "meter_reading",
                    "name": "Meter reading"
                  },
                  "channel": "whatsapp",
                  "status": "checked",
                  "status_name": "Checked",
                  "status_kind": "done",
                  "status_color": "green",
                  "priority": "normal",
                  "tags": [
                    "north"
                  ],
                  "due": null,
                  "assignee": {
                    "id": 12,
                    "name": "Sam"
                  },
                  "contact": {
                    "identity": "61412345678",
                    "name": "John Smith",
                    "phone": "61412345678",
                    "email": "",
                    "verified": true
                  },
                  "conversation_id": 8762,
                  "answers": {
                    "meter_no": "A-1182",
                    "reading": 48213,
                    "photo": [
                      9917
                    ],
                    "moving": false
                  },
                  "extra": {
                    "usage": 312
                  },
                  "location": null,
                  "parent": null,
                  "summary": "A-1182 · 48213",
                  "files_count": 1,
                  "files_pending": 0,
                  "unread": false,
                  "link": "https://www.app2email.com/s/4mXk9QpL2vTz8RwY3nBc6HdJ5sFg7Ka1",
                  "created": "2026-11-13T04:00:00.000Z",
                  "updated": "2026-11-13T04:20:00.000Z",
                  "status_changed": "2026-11-13T04:20:00.000Z",
                  "closed": "2026-11-13T04:20:00.000Z",
                  "files": [
                    {
                      "id": 9917,
                      "field": "photo",
                      "name": "IMG_5237.jpg",
                      "mime": "image/jpeg",
                      "size": 281733,
                      "state": "stored",
                      "source": "flow",
                      "url": "https://api.app2email.com/submit/file/c2FtcGxlLWZpbGUtbGluay1ub3QtcmVhbA",
                      "created": "2026-11-13T04:00:00.000Z"
                    }
                  ],
                  "events": [
                    {
                      "id": 60411,
                      "kind": "created",
                      "actor": {
                        "kind": "contact",
                        "id": 0,
                        "name": "John Smith"
                      },
                      "text": "",
                      "data": {},
                      "public": true,
                      "created": "2026-11-13T04:00:00.000Z"
                    }
                  ],
                  "fields": [
                    {
                      "key": "meter_no",
                      "label": "Meter number",
                      "type": "text",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "reading",
                      "label": "Meter reading",
                      "type": "number",
                      "step": "reading",
                      "internal": false,
                      "unit": "kWh"
                    },
                    {
                      "key": "photo",
                      "label": "Photo of the meter",
                      "type": "photo",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "moving",
                      "label": "Are you moving out?",
                      "type": "yesno",
                      "step": "reading",
                      "internal": false
                    },
                    {
                      "key": "billing_ref",
                      "label": "Billing reference",
                      "type": "text",
                      "step": "reading",
                      "internal": true
                    },
                    {
                      "key": "move_date",
                      "label": "Moving date",
                      "type": "date",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "new_address",
                      "label": "New address for the final bill",
                      "type": "textarea",
                      "step": "move",
                      "internal": false
                    },
                    {
                      "key": "usage",
                      "label": "Usage",
                      "type": "number",
                      "step": "",
                      "internal": true,
                      "unit": "kWh",
                      "calculated": true
                    }
                  ],
                  "stages": [
                    {
                      "key": "received",
                      "name": "Received",
                      "kind": "open",
                      "color": "blue",
                      "set_by": [],
                      "require_note": false
                    },
                    {
                      "key": "queried",
                      "name": "Queried",
                      "kind": "open",
                      "color": "amber",
                      "set_by": [],
                      "require_note": true
                    },
                    {
                      "key": "checked",
                      "name": "Checked",
                      "kind": "done",
                      "color": "green",
                      "set_by": [
                        "manager"
                      ],
                      "require_note": false
                    }
                  ],
                  "actions": [
                    {
                      "id": 31,
                      "label": "Send to billing"
                    }
                  ],
                  "buttons": []
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "deleteSubmission",
        "summary": "Delete a submission, or erase it for good",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Without `erase` the submission is hidden from every list and can be restored on the dashboard for 30 days; after that it is erased. With `erase=true` its rows, files and activity are removed now, for a privacy request: this cannot be undone, so confirm with the user first (erase also finds a submission that was deleted before). `submission.deleted` is sent, with `erased` saying which.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          },
          {
            "name": "erase",
            "in": "query",
            "required": false,
            "description": "true: remove the rows and files for good.",
            "type": "boolean",
            "default": false
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/SubmissionDeletedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s8del",
                "deleted": "MR-7Q3M2A",
                "id": 4182,
                "erased": false,
                "note": "The submission is hidden. It is erased for good after 30 days; until then the dashboard can restore it."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/submissions/{id}/notes": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "addSubmissionNote",
        "summary": "Write an internal note on a submission",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. A note for the team, up to 4,000 characters. The submitter never sees it. It appears in the activity list under the key's name, `submission.note_added` is sent, and automations with the trigger `note_added` run.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmissionNoteRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Written.",
            "schema": {
              "$ref": "#/definitions/SubmissionEventResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s5nte",
                "event": {
                  "id": 60420,
                  "kind": "note",
                  "actor": {
                    "kind": "api",
                    "id": 3,
                    "name": "API key Billing sync"
                  },
                  "text": "The customer called: the meter was replaced in October.",
                  "data": {},
                  "public": false,
                  "created": "2026-11-13T04:20:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/submissions/{id}/reply": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "replyToSubmission",
        "summary": "Message the submitter, with up to 3 buttons",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Sends `text` to the person who made the submission: on WhatsApp, or by e-mail when they gave only an e-mail address (`by` says which). When WhatsApp cannot take a normal message for them right now the reply is held (`held` true): they get a short notice, and the reply the moment they tap it or write to the number, exactly as a reply from the Inbox. `buttons` (up to 3) let them answer with one tap: each can move the submission to a stage (`set_status`), which is how a quote is accepted or a fix confirmed; a press arrives as `submission.customer_replied`. `file` sends a document or picture with it, `link` adds a button to their status page. A web submission whose number was never confirmed is answered by e-mail only. The reply is in the activity list and on the submitter's status page. 403 `submit_not_enabled` while Submit-Info is switched off; 502 `whatsapp_error` when it could not be sent at all.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmissionReplyRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent or held.",
            "schema": {
              "$ref": "#/definitions/SubmissionReplyResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s6rpl",
                "sent": true,
                "held": false,
                "by": "whatsapp",
                "event": {
                  "id": 60421,
                  "kind": "reply_out",
                  "actor": {
                    "kind": "api",
                    "id": 3,
                    "name": "API key Billing sync"
                  },
                  "text": "Is this still the right meter? The number on the photo is A-1128.",
                  "data": {
                    "state": "sent"
                  },
                  "public": true,
                  "created": "2026-11-13T04:20:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/submissions/{id}/files": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "addSubmissionFile",
        "summary": "Attach a file to a submission",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. One file as base64, 10 MB at most (413 `media_too_large` above that): a report, a signed form, a photo taken later. With `field` it joins that photo or document field's files; without it, it is a loose file of the submission. The file type is worked out from the bytes, not from `mime`. A submission holds at most 60 files. `submission.updated` is sent with `change.files.added`, and automations with the trigger `file_added` run.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmissionFileRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Stored.",
            "schema": {
              "$ref": "#/definitions/SubmissionFileResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s7fil",
                "file": {
                  "id": 9921,
                  "field": "",
                  "name": "report.pdf",
                  "mime": "application/pdf",
                  "size": 48211,
                  "state": "stored",
                  "source": "api",
                  "url": "https://api.app2email.com/submit/file/c2FtcGxlLWZpbGUtbGluay1ub3QtcmVhbA",
                  "created": "2026-11-13T04:20:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/submissions/{id}/run": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "runSubmissionAction",
        "summary": "Run a manual automation on a submission",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Runs one automation whose trigger is `manual` on this submission now: the same thing as its button in the inbox. `automation_id` is one of the submission's `actions[].id` (GET /submit/submissions/{id}); the automation must be switched on and belong to the submission's form (400 `invalid_automation` otherwise). The automation's conditions are still checked. The answer is the run with every step: what was sent to an outside system and what came back. A step that fails is inside the run (`steps[].ok` false, `status` failed), not an error of this call; when the server is busy the run is queued (`status` waiting) and shows in GET /submit/runs. Whatever the actions do is real: replies are sent, stages change, systems are called.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The submission's id, or its reference (MR-7Q3M2A).",
            "type": "string",
            "x-example": "MR-7Q3M2A"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmissionRunRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The run.",
            "schema": {
              "$ref": "#/definitions/SubmitRunResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "s9run",
                "run": {
                  "id": 9031,
                  "automation_id": 31,
                  "automation": "Price a quote request in the ERP",
                  "submission": "QR-4HT9XC",
                  "trigger": "manual",
                  "status": "ok",
                  "attempt": 1,
                  "steps": [
                    {
                      "n": 1,
                      "type": "http",
                      "ok": true,
                      "ms": 412,
                      "summary": "POST https://erp.example.com/api/quotes -> 201",
                      "error": "",
                      "request": {
                        "method": "POST",
                        "url": "https://erp.example.com/api/quotes",
                        "body": "{\"reference\":\"QR-4HT9XC\",\"product\":\"pump-s\",\"quantity\":3}"
                      },
                      "response": {
                        "status": 201,
                        "body": "{\"id\":\"Q-20931\",\"total\":720}"
                      }
                    },
                    {
                      "n": 2,
                      "type": "set_status",
                      "ok": true,
                      "ms": 9,
                      "summary": "Moved to Quoted",
                      "error": ""
                    },
                    {
                      "n": 3,
                      "type": "reply",
                      "ok": true,
                      "ms": 388,
                      "summary": "Sent on WhatsApp with 2 buttons",
                      "error": ""
                    }
                  ],
                  "error": "",
                  "test": false,
                  "created": "2026-11-13T04:00:00.000Z",
                  "finished": "2026-11-13T04:00:00.000Z",
                  "due": null
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/members": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listSubmitMembers",
        "summary": "The team: who works in the shared inbox",
        "description": "Scope: `submissions:manage`. The owner, the dashboard's members and the people invited to just the inbox, each with their role, what they may do now (`abilities`), which forms they see and how many open submissions they hold. A member's `id` is what `assignee` takes in PATCH /submit/submissions/{id} and what `member:<id>` means in an assign action.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The team.",
            "schema": {
              "$ref": "#/definitions/SubmitMembersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m1lst",
                "members": [
                  {
                    "id": 12,
                    "email": "sam@example.com",
                    "name": "Sam",
                    "role": "agent",
                    "status": "active",
                    "abilities": {
                      "note": true,
                      "reply": true,
                      "edit": true,
                      "stage": true,
                      "assign": false,
                      "files": true,
                      "export": true,
                      "delete": false,
                      "run": true,
                      "forms": false,
                      "automations": false,
                      "team": false
                    },
                    "overrides": {
                      "export": true
                    },
                    "forms": [],
                    "own_only": false,
                    "see_unassigned": true,
                    "hide_contacts": false,
                    "notify": {
                      "assigned": true,
                      "created": false
                    },
                    "invite_expired": false,
                    "invited": "2026-11-12T22:00:00.000Z",
                    "accepted": "2026-11-12T22:14:00.000Z",
                    "last_seen": "2026-11-13T04:00:00.000Z",
                    "open_count": 7
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "inviteSubmitMember",
        "summary": "Invite a person to the shared inbox by e-mail",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Sends an invitation e-mail with a link that works for 14 days. The person signs in (or makes a login) with that address and from then on sees the inbox, never the dashboard. `role` is a starting set of abilities (admin, manager, agent, viewer); `abilities` switches single ones on or off; `forms`, `own_only`, `see_unassigned` and `hide_contacts` narrow what they see. `email_sent` false means the e-mail could not go out: pass `invite_link` on yourself. An address that is a member already, or a full team (200 members), answers 400 `invalid_member`. Sends a real e-mail to a person: confirm the address with the user first.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitMemberInviteRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Invited.",
            "schema": {
              "$ref": "#/definitions/SubmitMemberResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m2inv",
                "member": {
                  "id": 12,
                  "email": "sam@example.com",
                  "name": "Sam",
                  "role": "agent",
                  "status": "invited",
                  "abilities": {
                    "note": true,
                    "reply": true,
                    "edit": true,
                    "stage": true,
                    "assign": false,
                    "files": true,
                    "export": true,
                    "delete": false,
                    "run": true,
                    "forms": false,
                    "automations": false,
                    "team": false
                  },
                  "overrides": {
                    "export": true
                  },
                  "forms": [],
                  "own_only": false,
                  "see_unassigned": true,
                  "hide_contacts": false,
                  "notify": {
                    "assigned": true,
                    "created": false
                  },
                  "invite_expired": false,
                  "invited": "2026-11-12T22:00:00.000Z",
                  "accepted": null,
                  "last_seen": null,
                  "open_count": 0
                },
                "invite_link": "https://www.app2email.com/desk-invite/Jq7mXk9QpL2vTz8RwY3nBc6HdJ5sFg7K",
                "email_sent": true,
                "note": "The invitation was e-mailed. The link works for 14 days."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/members/{id}": {
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "updateSubmitMember",
        "summary": "Change a member's role, abilities or forms",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Any of `name`, `role`, `abilities`, `forms`, `own_only`, `see_unassigned`, `hide_contacts`, `notify`; what is left out stays (400 `invalid_member` when the body names none). `abilities` replaces the member's own changes to the role's set: `{\"delete\": false}` takes one ability away from a manager. The owner's own row cannot be changed (400 `invalid_member`).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The member's id (GET /submit/members).",
            "type": "string",
            "x-example": "12"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitMemberUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed.",
            "schema": {
              "$ref": "#/definitions/SubmitMemberResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m3upd",
                "member": {
                  "id": 12,
                  "email": "sam@example.com",
                  "name": "Sam",
                  "role": "manager",
                  "status": "active",
                  "abilities": {
                    "note": true,
                    "reply": true,
                    "edit": true,
                    "stage": true,
                    "assign": false,
                    "files": true,
                    "export": true,
                    "delete": false,
                    "run": true,
                    "forms": false,
                    "automations": false,
                    "team": false
                  },
                  "overrides": {
                    "delete": false
                  },
                  "forms": [],
                  "own_only": false,
                  "see_unassigned": true,
                  "hide_contacts": false,
                  "notify": {
                    "assigned": true,
                    "created": false
                  },
                  "invite_expired": false,
                  "invited": "2026-11-12T22:00:00.000Z",
                  "accepted": "2026-11-12T22:14:00.000Z",
                  "last_seen": "2026-11-13T04:00:00.000Z",
                  "open_count": 7
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "removeSubmitMember",
        "summary": "Remove a member from the inbox",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. The person loses access at once. What they did stays in the activity lists under their name, and what they hold stays assigned to their name until it is reassigned (PATCH /submit/submissions/{id} `assignee`). The owner cannot be removed (400 `invalid_member`).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The member's id (GET /submit/members).",
            "type": "string",
            "x-example": "12"
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "schema": {
              "$ref": "#/definitions/SubmitMemberRemovedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "m4rem",
                "deleted": 12,
                "note": "The member has no access any more. What they hold stays assigned to their name until it is reassigned."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/automations": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listAutomations",
        "summary": "The automations",
        "description": "Scope: `submissions:manage`. Every automation with its whole document, a one-sentence summary (`sentence`), how often it ran and failed, and its last error. `form` empty means it runs for every form.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "form",
            "in": "query",
            "required": false,
            "description": "Only the automations of this form (its key).",
            "type": "string",
            "x-example": "quote"
          }
        ],
        "responses": {
          "200": {
            "description": "The automations.",
            "schema": {
              "$ref": "#/definitions/SubmitAutomationsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a1lst",
                "automations": [
                  {
                    "name": "Price a quote request in the ERP",
                    "form": "quote",
                    "enabled": true,
                    "trigger": "submitted",
                    "options": {},
                    "conditions": {
                      "all": [
                        {
                          "field": "quantity",
                          "gt": 0
                        }
                      ]
                    },
                    "actions": [
                      {
                        "type": "http",
                        "connection": "erp",
                        "method": "POST",
                        "path": "/quotes",
                        "query": {},
                        "headers": {
                          "X-Source": "whatsapp"
                        },
                        "body": {
                          "reference": "{reference}",
                          "customer": {
                            "name": "{contact.name}",
                            "phone": "{contact.phone}"
                          },
                          "product": "{product}",
                          "quantity": "{quantity}",
                          "photos": "{files.photos}"
                        },
                        "save": {
                          "erp_id": "$.id",
                          "quote_amount": "$.total"
                        },
                        "on_fail": "retry"
                      },
                      {
                        "type": "set_status",
                        "status": "quoted",
                        "note": "Priced by the ERP"
                      },
                      {
                        "type": "reply",
                        "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                        "buttons": [
                          {
                            "id": "accept",
                            "title": "Accept",
                            "set_status": "accepted"
                          },
                          {
                            "id": "decline",
                            "title": "Decline",
                            "set_status": "declined"
                          }
                        ],
                        "file": "",
                        "link": true
                      }
                    ],
                    "id": 31,
                    "position": 0,
                    "sentence": "When a Quote request is submitted, if quantity > 0: call ERP (POST /quotes), move to Quoted, reply with Accept / Decline",
                    "runs": 18,
                    "failures": 1,
                    "last_run": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "created": "2026-11-12T22:30:00.000Z",
                    "updated": "2026-11-12T22:30:00.000Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "createAutomation",
        "summary": "Create an automation: when, if, do",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. `trigger` says when it runs (submitted, a stage change, a button the customer pressed, overdue, manual ...), `conditions` is a rule that must hold (or null), `actions` run in order: reply, e-mail, move the stage, assign, calculate, call an outside system through a connection and save parts of its answer, wait, and more. The SubmitAutomationInput schema lists every trigger, action, placeholder and formula function. The document is checked as a whole: 400 `invalid_automation` with each problem's path and a fix. Before switching one on, try it on a real submission with POST /submit/automations/try. A number has at most 200 automations.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitAutomationInput"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/SubmitAutomationResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a2crt",
                "automation": {
                  "name": "Price a quote request in the ERP",
                  "form": "quote",
                  "enabled": true,
                  "trigger": "submitted",
                  "options": {},
                  "conditions": {
                    "all": [
                      {
                        "field": "quantity",
                        "gt": 0
                      }
                    ]
                  },
                  "actions": [
                    {
                      "type": "http",
                      "connection": "erp",
                      "method": "POST",
                      "path": "/quotes",
                      "query": {},
                      "headers": {
                        "X-Source": "whatsapp"
                      },
                      "body": {
                        "reference": "{reference}",
                        "customer": {
                          "name": "{contact.name}",
                          "phone": "{contact.phone}"
                        },
                        "product": "{product}",
                        "quantity": "{quantity}",
                        "photos": "{files.photos}"
                      },
                      "save": {
                        "erp_id": "$.id",
                        "quote_amount": "$.total"
                      },
                      "on_fail": "retry"
                    },
                    {
                      "type": "set_status",
                      "status": "quoted",
                      "note": "Priced by the ERP"
                    },
                    {
                      "type": "reply",
                      "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                      "buttons": [
                        {
                          "id": "accept",
                          "title": "Accept",
                          "set_status": "accepted"
                        },
                        {
                          "id": "decline",
                          "title": "Decline",
                          "set_status": "declined"
                        }
                      ],
                      "file": "",
                      "link": true
                    }
                  ],
                  "id": 31,
                  "position": 0,
                  "sentence": "When a Quote request is submitted, if quantity > 0: call ERP (POST /quotes), move to Quoted, reply with Accept / Decline",
                  "runs": 0,
                  "failures": 0,
                  "last_run": null,
                  "last_error": "",
                  "created": "2026-11-12T22:30:00.000Z",
                  "updated": "2026-11-12T22:30:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/automations/try": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "tryAutomation",
        "summary": "Try an automation on a real submission, saving and sending nothing",
        "description": "Scope: `submissions:manage`. A sandbox key may use it. A rehearsal. Send the automation document (it need not be saved; the id of a saved one works too) and a real submission's id or reference of the same form: the conditions are evaluated and every action is prepared with that submission's values, so the answer shows each step with the filled-in texts and requests. Nothing is written to the submission and nothing is sent to the customer. With `call` true the http, openapi and mcp actions really call the outside system, so you can see its answer and check your `save` paths; without it their requests are only shown. A call that fails is a failed step inside the run, never an error of this route. The run of a try is not stored: its `id` is 0.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitAutomationTryRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The rehearsal's run.",
            "schema": {
              "$ref": "#/definitions/SubmitRunResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a6try",
                "run": {
                  "id": 0,
                  "automation_id": 0,
                  "automation": "Price a quote request in the ERP",
                  "submission": "QR-4HT9XC",
                  "trigger": "submitted",
                  "status": "ok",
                  "attempt": 1,
                  "steps": [
                    {
                      "n": 1,
                      "type": "http",
                      "ok": true,
                      "ms": 412,
                      "summary": "POST https://erp.example.com/api/quotes -> 201",
                      "error": "",
                      "request": {
                        "method": "POST",
                        "url": "https://erp.example.com/api/quotes",
                        "body": "{\"reference\":\"QR-4HT9XC\",\"product\":\"pump-s\",\"quantity\":3}"
                      },
                      "response": {
                        "status": 201,
                        "body": "{\"id\":\"Q-20931\",\"total\":720}"
                      }
                    },
                    {
                      "n": 2,
                      "type": "set_status",
                      "ok": true,
                      "ms": 9,
                      "summary": "Moved to Quoted",
                      "error": ""
                    },
                    {
                      "n": 3,
                      "type": "reply",
                      "ok": true,
                      "ms": 388,
                      "summary": "Sent on WhatsApp with 2 buttons",
                      "error": ""
                    }
                  ],
                  "error": "",
                  "test": true,
                  "created": "2026-11-13T04:00:00.000Z",
                  "finished": "2026-11-13T04:00:00.000Z",
                  "due": null
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/automations/{id}": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getAutomation",
        "summary": "One automation",
        "description": "Scope: `submissions:manage`. The whole document with its id, summary sentence and counters. Read it before changing it: PUT takes the whole document back.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The automation's id (GET /submit/automations).",
            "type": "string",
            "x-example": "31"
          }
        ],
        "responses": {
          "200": {
            "description": "The automation.",
            "schema": {
              "$ref": "#/definitions/SubmitAutomationResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a3get",
                "automation": {
                  "name": "Price a quote request in the ERP",
                  "form": "quote",
                  "enabled": true,
                  "trigger": "submitted",
                  "options": {},
                  "conditions": {
                    "all": [
                      {
                        "field": "quantity",
                        "gt": 0
                      }
                    ]
                  },
                  "actions": [
                    {
                      "type": "http",
                      "connection": "erp",
                      "method": "POST",
                      "path": "/quotes",
                      "query": {},
                      "headers": {
                        "X-Source": "whatsapp"
                      },
                      "body": {
                        "reference": "{reference}",
                        "customer": {
                          "name": "{contact.name}",
                          "phone": "{contact.phone}"
                        },
                        "product": "{product}",
                        "quantity": "{quantity}",
                        "photos": "{files.photos}"
                      },
                      "save": {
                        "erp_id": "$.id",
                        "quote_amount": "$.total"
                      },
                      "on_fail": "retry"
                    },
                    {
                      "type": "set_status",
                      "status": "quoted",
                      "note": "Priced by the ERP"
                    },
                    {
                      "type": "reply",
                      "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                      "buttons": [
                        {
                          "id": "accept",
                          "title": "Accept",
                          "set_status": "accepted"
                        },
                        {
                          "id": "decline",
                          "title": "Decline",
                          "set_status": "declined"
                        }
                      ],
                      "file": "",
                      "link": true
                    }
                  ],
                  "id": 31,
                  "position": 0,
                  "sentence": "When a Quote request is submitted, if quantity > 0: call ERP (POST /quotes), move to Quoted, reply with Accept / Decline",
                  "runs": 18,
                  "failures": 1,
                  "last_run": "2026-11-13T04:00:00.000Z",
                  "last_error": "",
                  "created": "2026-11-12T22:30:00.000Z",
                  "updated": "2026-11-12T22:30:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "updateAutomation",
        "summary": "Change an automation, or switch it on or off",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Send the whole document (with `trigger` and `actions`) to replace it, or a body with neither of those to change only the keys it has: `{\"enabled\": false}` switches it off and keeps the rest. The result is checked as a whole (400 `invalid_automation`). Runs that are waiting (a `wait` action, a retry) continue with the new document.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The automation's id (GET /submit/automations).",
            "type": "string",
            "x-example": "31"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitAutomationUpdateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/SubmitAutomationResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a4upd",
                "automation": {
                  "name": "Price a quote request in the ERP",
                  "form": "quote",
                  "enabled": false,
                  "trigger": "submitted",
                  "options": {},
                  "conditions": {
                    "all": [
                      {
                        "field": "quantity",
                        "gt": 0
                      }
                    ]
                  },
                  "actions": [
                    {
                      "type": "http",
                      "connection": "erp",
                      "method": "POST",
                      "path": "/quotes",
                      "query": {},
                      "headers": {
                        "X-Source": "whatsapp"
                      },
                      "body": {
                        "reference": "{reference}",
                        "customer": {
                          "name": "{contact.name}",
                          "phone": "{contact.phone}"
                        },
                        "product": "{product}",
                        "quantity": "{quantity}",
                        "photos": "{files.photos}"
                      },
                      "save": {
                        "erp_id": "$.id",
                        "quote_amount": "$.total"
                      },
                      "on_fail": "retry"
                    },
                    {
                      "type": "set_status",
                      "status": "quoted",
                      "note": "Priced by the ERP"
                    },
                    {
                      "type": "reply",
                      "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                      "buttons": [
                        {
                          "id": "accept",
                          "title": "Accept",
                          "set_status": "accepted"
                        },
                        {
                          "id": "decline",
                          "title": "Decline",
                          "set_status": "declined"
                        }
                      ],
                      "file": "",
                      "link": true
                    }
                  ],
                  "id": 31,
                  "position": 0,
                  "sentence": "When a Quote request is submitted, if quantity > 0: call ERP (POST /quotes), move to Quoted, reply with Accept / Decline",
                  "runs": 18,
                  "failures": 1,
                  "last_run": "2026-11-13T04:00:00.000Z",
                  "last_error": "",
                  "created": "2026-11-12T22:30:00.000Z",
                  "updated": "2026-11-12T22:30:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "deleteAutomation",
        "summary": "Delete an automation",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. It stops running, and its waiting runs are dropped. The run log of what it did stays for 30 days.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The automation's id (GET /submit/automations).",
            "type": "string",
            "x-example": "31"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/SubmitDeletedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "a5del",
                "deleted": true,
                "id": 31
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/runs": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listAutomationRuns",
        "summary": "The automation run log, step by step",
        "description": "Scope: `submissions:manage`. Latest first, kept 30 days. Each run names its automation, submission and trigger and lists every step: the action, whether it worked, how long it took, and for outside calls the request that was sent and the start of the answer. Use `status=failed` to find what went wrong, `status=waiting` for runs paused by a wait or between retries. Page with `next_cursor`. An `automation` or `submission` filter that names nothing answers 404.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "automation",
            "in": "query",
            "required": false,
            "description": "Only this automation's runs (its id).",
            "type": "integer",
            "x-example": 31
          },
          {
            "name": "submission",
            "in": "query",
            "required": false,
            "description": "Only the runs on this submission (id or reference).",
            "type": "string",
            "x-example": "QR-4HT9XC"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only this status.",
            "type": "string",
            "enum": [
              "running",
              "ok",
              "failed",
              "waiting",
              "skipped"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The runs.",
            "schema": {
              "$ref": "#/definitions/SubmitRunsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "r1lst",
                "runs": [
                  {
                    "id": 9031,
                    "automation_id": 31,
                    "automation": "Price a quote request in the ERP",
                    "submission": "QR-4HT9XC",
                    "trigger": "submitted",
                    "status": "ok",
                    "attempt": 1,
                    "steps": [
                      {
                        "n": 1,
                        "type": "http",
                        "ok": true,
                        "ms": 412,
                        "summary": "POST https://erp.example.com/api/quotes -> 201",
                        "error": "",
                        "request": {
                          "method": "POST",
                          "url": "https://erp.example.com/api/quotes",
                          "body": "{\"reference\":\"QR-4HT9XC\",\"product\":\"pump-s\",\"quantity\":3}"
                        },
                        "response": {
                          "status": 201,
                          "body": "{\"id\":\"Q-20931\",\"total\":720}"
                        }
                      },
                      {
                        "n": 2,
                        "type": "set_status",
                        "ok": true,
                        "ms": 9,
                        "summary": "Moved to Quoted",
                        "error": ""
                      },
                      {
                        "n": 3,
                        "type": "reply",
                        "ok": true,
                        "ms": 388,
                        "summary": "Sent on WhatsApp with 2 buttons",
                        "error": ""
                      }
                    ],
                    "error": "",
                    "test": false,
                    "created": "2026-11-13T04:00:00.000Z",
                    "finished": "2026-11-13T04:00:00.000Z",
                    "due": null
                  }
                ],
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/connections": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listConnections",
        "summary": "The connections to outside systems",
        "description": "Scope: `submissions:manage`. The systems automations can call: plain HTTP APIs, APIs described by an OpenAPI document, and MCP servers. Each with its kind, address, sign-in type (`has_secret`, never the secret), how many operations or tools are known, the last time it worked, its last error and the automations that use it.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The connections.",
            "schema": {
              "$ref": "#/definitions/SubmitConnectionsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c1lst",
                "connections": [
                  {
                    "key": "erp",
                    "name": "ERP",
                    "kind": "http",
                    "base_url": "https://erp.example.com/api",
                    "auth": {
                      "type": "bearer",
                      "name": "",
                      "username": "",
                      "has_secret": true
                    },
                    "headers": {
                      "X-Tenant": "acme"
                    },
                    "spec_url": "",
                    "enabled": true,
                    "functions_count": 0,
                    "functions_at": null,
                    "last_ok": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "used_by": [
                      "Price a quote request in the ERP"
                    ]
                  },
                  {
                    "key": "helpdesk",
                    "name": "Helpdesk",
                    "kind": "openapi",
                    "base_url": "https://helpdesk.example.com/api",
                    "auth": {
                      "type": "header",
                      "name": "X-Auth-Token",
                      "username": "",
                      "has_secret": true
                    },
                    "headers": {},
                    "spec_url": "https://helpdesk.example.com/openapi.json",
                    "enabled": true,
                    "functions_count": 2,
                    "functions_at": "2026-11-13T04:00:00.000Z",
                    "last_ok": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "used_by": []
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/connections/{key}": {
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "setConnection",
        "summary": "Create or change a connection (HTTP, OpenAPI or MCP)",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Makes the connection when the key is new (`name` and `kind` are needed then), else changes it: a body without `kind` changes only the keys it names. `kind` http: a base address and a sign-in. openapi: also `spec_url` (or `spec`), an OpenAPI 3 document in JSON. mcp: `base_url` is the MCP server's address. `auth.secret` is write-only: it is stored encrypted, never returned, and kept when a later PUT leaves it out (a changed address needs it again). Addresses must be https and public. Saving does not call the outside system: a posted `spec` is read into operations at once, a `spec_url` and an MCP server's tools are read by POST /submit/connections/{key}/refresh. Next: POST /submit/connections/{key}/test, then refresh (openapi, mcp) and GET /submit/connections/{key}/functions to see what an action can call. A number has at most 30 connections.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The connection's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "erp"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SubmitConnectionInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/SubmitConnectionResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c2set",
                "connection": {
                  "key": "erp",
                  "name": "ERP",
                  "kind": "http",
                  "base_url": "https://erp.example.com/api",
                  "auth": {
                    "type": "bearer",
                    "name": "",
                    "username": "",
                    "has_secret": true
                  },
                  "headers": {
                    "X-Tenant": "acme"
                  },
                  "spec_url": "",
                  "enabled": true,
                  "functions_count": 0,
                  "functions_at": null,
                  "last_ok": null,
                  "last_error": "",
                  "used_by": []
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "deleteConnection",
        "summary": "Delete a connection",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Refused while an automation still uses it: 409 `connection_in_use`, and the message names those automations. The stored secret is deleted with it.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The connection's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "erp"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/SubmitDeletedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c3del",
                "deleted": true,
                "key": "erp"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/connections/{key}/test": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "testConnection",
        "summary": "Test a connection: can app2email reach it and sign in?",
        "description": "Scope: `submissions:manage`. A sandbox key may use it. Makes one real call from app2email's server: http reads the base address, openapi fetches the document, mcp opens a session with the server. The answer says whether it worked (`ok`), how far it got (`stage`), the HTTP status, the error in words and the time taken. A failed test answers 200 with `ok` false: read `stage` and `error` (`stage` is `response` when it worked). Nothing is changed in the outside system.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The connection's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "erp"
          }
        ],
        "responses": {
          "200": {
            "description": "The test's result.",
            "schema": {
              "$ref": "#/definitions/SubmitConnectionTestResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4tst",
                "ok": true,
                "stage": "response",
                "status": 200,
                "error": "",
                "ms": 231
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/connections/{key}/refresh": {
      "post": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "refreshConnection",
        "summary": "Read a connection's operations or tools again",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. For openapi: fetches the document again and rebuilds the list of operations. For mcp: asks the server for its tools again. Call it after the outside system changed. An automation that names an operation or tool that is gone fails at its next run, so check GET /submit/automations afterwards. 502 `connection_failed` when the document or the server cannot be read; the old list is kept then.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The connection's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "erp"
          }
        ],
        "responses": {
          "200": {
            "description": "Read again.",
            "schema": {
              "$ref": "#/definitions/SubmitConnectionResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c5ref",
                "connection": {
                  "key": "helpdesk",
                  "name": "Helpdesk",
                  "kind": "openapi",
                  "base_url": "https://helpdesk.example.com/api",
                  "auth": {
                    "type": "header",
                    "name": "X-Auth-Token",
                    "username": "",
                    "has_secret": true
                  },
                  "headers": {},
                  "spec_url": "https://helpdesk.example.com/openapi.json",
                  "enabled": true,
                  "functions_count": 2,
                  "functions_at": "2026-11-13T04:00:00.000Z",
                  "last_ok": "2026-11-13T04:00:00.000Z",
                  "last_error": "",
                  "used_by": []
                },
                "functions": [
                  {
                    "id": "createTicket",
                    "title": "Create a ticket",
                    "method": "POST",
                    "path": "/tickets",
                    "has_body": true,
                    "params": [
                      {
                        "name": "subject",
                        "in": "body",
                        "type": "string",
                        "required": true,
                        "description": "The ticket's title."
                      },
                      {
                        "name": "priority",
                        "in": "body",
                        "type": "string",
                        "required": false,
                        "description": "low, normal or high."
                      }
                    ]
                  },
                  {
                    "id": "getTicket",
                    "title": "One ticket",
                    "method": "GET",
                    "path": "/tickets/{id}",
                    "has_body": false,
                    "params": [
                      {
                        "name": "id",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "description": ""
                      }
                    ]
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/connections/{key}/functions": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "listConnectionFunctions",
        "summary": "What an action can call on a connection",
        "description": "Scope: `submissions:manage`. The operations of an openapi connection or the tools of an mcp connection, each with its parameters: name, where it goes (path, query, header, body), type and whether it is required. An openapi action takes a function's `id` as `operation` and fills `params` by name; an mcp action takes it as `tool` and fills `arguments`. An http connection has no functions: its actions name method and path themselves.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "The connection's key: lower case letters, digits and _, starting with a letter.",
            "type": "string",
            "x-example": "erp"
          }
        ],
        "responses": {
          "200": {
            "description": "The functions.",
            "schema": {
              "$ref": "#/definitions/SubmitConnectionFunctionsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c6fun",
                "functions": [
                  {
                    "id": "createTicket",
                    "title": "Create a ticket",
                    "method": "POST",
                    "path": "/tickets",
                    "has_body": true,
                    "params": [
                      {
                        "name": "subject",
                        "in": "body",
                        "type": "string",
                        "required": true,
                        "description": "The ticket's title."
                      },
                      {
                        "name": "priority",
                        "in": "body",
                        "type": "string",
                        "required": false,
                        "description": "low, normal or high."
                      }
                    ]
                  },
                  {
                    "id": "getTicket",
                    "title": "One ticket",
                    "method": "GET",
                    "path": "/tickets/{id}",
                    "has_body": false,
                    "params": [
                      {
                        "name": "id",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "description": ""
                      }
                    ]
                  }
                ],
                "functions_at": "2026-11-13T04:00:00.000Z"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/submit/report": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getSubmitReport",
        "summary": "Submission counts by form, stage, day and assignee",
        "description": "Scope: `submissions:manage`. The submissions made in the last `days` days (1 to 365, default 30) counted by form, by stage, by day (in the business time zone) and by assignee, with how many are open now and the average hours from submission to a closed stage. 400 `invalid_range` when `days` is not 1 to 365.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1 to 365. Default 30.",
            "type": "integer",
            "minimum": 1,
            "maximum": 365,
            "default": 30
          }
        ],
        "responses": {
          "200": {
            "description": "The report.",
            "schema": {
              "$ref": "#/definitions/SubmitReportResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "r9rep",
                "days": 30,
                "timezone": "Australia/Sydney",
                "open_now": 14,
                "closed_avg_hours": 6.4,
                "by_form": [
                  {
                    "form": "meter_reading",
                    "name": "Meter reading",
                    "count": 148,
                    "open": 12
                  },
                  {
                    "form": "quote",
                    "name": "Quote request",
                    "count": 23,
                    "open": 2
                  }
                ],
                "by_stage": [
                  {
                    "form": "meter_reading",
                    "status": "received",
                    "status_kind": "open",
                    "count": 12
                  },
                  {
                    "form": "meter_reading",
                    "status": "checked",
                    "status_kind": "done",
                    "count": 134
                  }
                ],
                "by_day": [
                  {
                    "day": "2026-11-12",
                    "count": 9
                  },
                  {
                    "day": "2026-11-13",
                    "count": 4
                  }
                ],
                "by_assignee": [
                  {
                    "id": 12,
                    "name": "Sam",
                    "count": 61,
                    "open": 7
                  },
                  {
                    "id": 0,
                    "name": "",
                    "count": 14,
                    "open": 7
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates/delete": {
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "deleteTemplates",
        "summary": "Delete several templates at once (all or nothing)",
        "description": "Needs 'templates:manage'. names (every language) or ids, at most 100 languages; one bad id deletes nothing. WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TemplateBulkDeleteRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/TemplateBulkDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t3blk",
                "deleted": [
                  {
                    "name": "summer_sale",
                    "language": "en",
                    "id": "1234567891"
                  },
                  {
                    "name": "old_promo",
                    "language": "en",
                    "id": "1234567892"
                  },
                  {
                    "name": "old_promo",
                    "language": "de",
                    "id": "1234567893"
                  }
                ],
                "note": "Deleted on the whole WhatsApp Business Account. An approved template's name and language can be used again after 30 days."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates/{name}/archive": {
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "archiveTemplate",
        "summary": "Archive a template (deleted by WhatsApp after 28 days)",
        "description": "Needs 'templates:manage'. Every language, or ?language=. Only APPROVED or REJECTED templates; unarchive within 28 days to keep it. WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The template's name.",
            "type": "string",
            "x-example": "order_update"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Only this language. Default: every language.",
            "type": "string",
            "x-example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Archived (failed lists the languages WhatsApp refused).",
            "schema": {
              "$ref": "#/definitions/TemplateArchiveResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t4arc",
                "name": "summer_sale",
                "archived": [
                  {
                    "language": "en",
                    "id": "1234567891"
                  }
                ],
                "failed": [],
                "note": "Archived on the whole WhatsApp Business Account. WhatsApp deletes archived templates 28 days after archiving; unarchive before then to keep them."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates/{name}/unarchive": {
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "unarchiveTemplate",
        "summary": "Unarchive a template",
        "description": "Needs 'templates:manage'. Back to its previous status. Within 28 days of archiving. WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The template's name.",
            "type": "string",
            "x-example": "order_update"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Only this language. Default: every language.",
            "type": "string",
            "x-example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Unarchived.",
            "schema": {
              "$ref": "#/definitions/TemplateArchiveResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t4una",
                "name": "summer_sale",
                "unarchived": [
                  {
                    "language": "en",
                    "id": "1234567891"
                  }
                ],
                "failed": [],
                "note": "Unarchived: back to their previous status (or APPROVED) on the whole WhatsApp Business Account."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates/{name}/compare": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "compareTemplates",
        "summary": "Compare two templates: block rate, sends, top block reason",
        "description": "Both templates of this account, each sent at least 1,000 times in the period.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The template's name.",
            "type": "string",
            "x-example": "order_update"
          },
          {
            "name": "with",
            "in": "query",
            "required": true,
            "description": "The other template's name.",
            "type": "string",
            "x-example": "summer_sale_v2"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "The template's language (eg en, en_US). Needed when the template has several.",
            "type": "string",
            "x-example": "en"
          },
          {
            "name": "with_language",
            "in": "query",
            "required": false,
            "description": "The other template's language.",
            "type": "string",
            "x-example": "en"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How far back: 7, 30, 60 or 90 days.",
            "type": "integer",
            "enum": [
              7,
              30,
              60,
              90
            ],
            "default": 30
          }
        ],
        "responses": {
          "200": {
            "description": "Meta's comparison.",
            "schema": {
              "$ref": "#/definitions/TemplateCompareResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t5cmp",
                "template": {
                  "name": "summer_sale",
                  "language": "en",
                  "id": "5289179717853347"
                },
                "with": {
                  "name": "summer_sale_v2",
                  "language": "en",
                  "id": "1533406637136032"
                },
                "days": 30,
                "since": "2026-10-07T01:00:00.000Z",
                "until": "2026-11-06T01:00:00.000Z",
                "metrics": [
                  {
                    "metric": "BLOCK_RATE",
                    "type": "RELATIVE",
                    "order_by_relative_metric": [
                      "1533406637136032",
                      "5289179717853347"
                    ]
                  },
                  {
                    "metric": "MESSAGE_SENDS",
                    "type": "NUMBER_VALUES",
                    "number_values": [
                      {
                        "key": "5289179717853347",
                        "value": 1273
                      },
                      {
                        "key": "1533406637136032",
                        "value": 1042
                      }
                    ]
                  },
                  {
                    "metric": "TOP_BLOCK_REASON",
                    "type": "STRING_VALUES",
                    "string_values": [
                      {
                        "key": "5289179717853347",
                        "value": "UNKNOWN_BLOCK_REASON"
                      },
                      {
                        "key": "1533406637136032",
                        "value": "UNKNOWN_BLOCK_REASON"
                      }
                    ]
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/templates/{name}/authentication": {
      "put": {
        "tags": [
          "Templates"
        ],
        "operationId": "upsertAuthTemplate",
        "summary": "Create or update an authentication template in many languages",
        "description": "Needs 'templates:manage'. Missing languages are created, existing ones updated, in one call. Not for business-scoped user ids (131062). WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The authentication template's name.",
            "type": "string",
            "x-example": "verify_code"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TemplateAuthUpsertRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Created or updated, per language.",
            "schema": {
              "$ref": "#/definitions/TemplateAuthUpsertResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t8ups",
                "name": "verify_code",
                "category": "AUTHENTICATION",
                "templates": [
                  {
                    "language": "en_US",
                    "id": "954638012257287",
                    "status": "APPROVED"
                  },
                  {
                    "language": "es_ES",
                    "id": "969725527415202",
                    "status": "APPROVED"
                  }
                ],
                "note": "Created or updated in every language listed, on the whole WhatsApp Business Account. Send it with the code as the body parameter and the copy-code button parameter."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/template-previews": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "previewAuthTemplates",
        "summary": "Authentication template texts, per language",
        "description": "The fixed texts WhatsApp puts into an authentication template (body, security line, expiry footer, buttons).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "description": "Comma separated (eg en_US,es_ES). Default: every language.",
            "type": "string",
            "x-example": "en_US,es_ES"
          },
          {
            "name": "add_security_recommendation",
            "in": "query",
            "required": false,
            "description": "With the security line.",
            "type": "boolean"
          },
          {
            "name": "code_expiration_minutes",
            "in": "query",
            "required": false,
            "description": "With the expiry footer (1 to 90).",
            "type": "integer",
            "minimum": 1,
            "maximum": 90
          }
        ],
        "responses": {
          "200": {
            "description": "The previews.",
            "schema": {
              "$ref": "#/definitions/TemplatePreviewsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t9prv",
                "category": "AUTHENTICATION",
                "previews": [
                  {
                    "language": "en_US",
                    "body": "*{{1}}* is your verification code. For your security, do not share this code.",
                    "footer": "This code expires in 10 minutes.",
                    "buttons": [
                      {
                        "autofill_text": "Autofill",
                        "text": "Copy code"
                      }
                    ]
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/template-library": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "listTemplateLibrary",
        "summary": "Meta's Template Library (pre-approved templates)",
        "description": "Utility and authentication templates written by Meta. Create one with POST /templates and library_template_name.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Words in the template.",
            "type": "string",
            "x-example": "delivery"
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "description": "eg ORDER_MANAGEMENT, PAYMENTS, ACCOUNT_UPDATE, CUSTOMER_FEEDBACK.",
            "type": "string"
          },
          {
            "name": "usecase",
            "in": "query",
            "required": false,
            "description": "eg SHIPMENT_CONFIRMATION, PAYMENT_DUE_REMINDER.",
            "type": "string"
          },
          {
            "name": "industry",
            "in": "query",
            "required": false,
            "description": "E_COMMERCE or FINANCIAL_SERVICES.",
            "type": "string"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "eg en_US.",
            "type": "string"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "A library template's name.",
            "type": "string"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 200.",
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor of the previous answer.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Library templates.",
            "schema": {
              "$ref": "#/definitions/TemplateLibraryResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t6lib",
                "templates": [
                  {
                    "name": "delivery_update_1",
                    "language": "en_US",
                    "category": "UTILITY",
                    "topic": "ORDER_MANAGEMENT",
                    "usecase": "DELIVERY_UPDATE",
                    "industry": [
                      "E_COMMERCE"
                    ],
                    "body": "Good news! Your order {{1}} is on its way. Track it here.",
                    "body_params": [
                      "#12345"
                    ],
                    "body_param_types": [
                      "TEXT"
                    ],
                    "buttons": [
                      {
                        "type": "URL",
                        "text": "Track order",
                        "url": "https://www.example.com/"
                      }
                    ],
                    "id": "7147013345418927"
                  }
                ],
                "next_cursor": null,
                "note": "Create one with POST /v1/4976659348270/templates {\"name\", \"language\", \"category\", \"library_template_name\", \"library_template_button_inputs\"}."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/template-insights": {
      "get": {
        "tags": [
          "Templates"
        ],
        "operationId": "getTemplateInsights",
        "summary": "Template insights: sent, delivered, read, clicked, cost",
        "description": "Per template and day (UTC), 90 days back, at most 10 template languages. Insights must be on (POST); not for EU or Japan accounts.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "templates",
            "in": "query",
            "required": true,
            "description": "Template names, comma separated.",
            "type": "string",
            "x-example": "summer_sale"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Only this language.",
            "type": "string"
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "First day, YYYY-MM-DD. Default: 6 days before until.",
            "type": "string"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "Last day, YYYY-MM-DD. Default: today.",
            "type": "string"
          },
          {
            "name": "metrics",
            "in": "query",
            "required": false,
            "description": "Comma separated: sent, delivered, read, clicked, cost. Default: all.",
            "type": "string"
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "description": "cloud_api (default) or marketing_messages.",
            "type": "string",
            "enum": [
              "cloud_api",
              "marketing_messages"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Daily numbers.",
            "schema": {
              "$ref": "#/definitions/TemplateInsightsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t7get",
                "since": "2026-10-31",
                "until": "2026-11-06",
                "product": "cloud_api",
                "templates": [
                  {
                    "name": "summer_sale",
                    "language": "en",
                    "id": "1234567891"
                  }
                ],
                "data_points": [
                  {
                    "template": "summer_sale",
                    "language": "en",
                    "template_id": "1234567891",
                    "date": "2026-11-05",
                    "sent": 1200,
                    "delivered": 1150,
                    "read": 870,
                    "clicked": [
                      {
                        "type": "url_button",
                        "button_content": "Shop now",
                        "count": 96
                      }
                    ],
                    "cost": [
                      {
                        "type": "amount_spent",
                        "value": 30.12
                      },
                      {
                        "type": "cost_per_delivered",
                        "value": 0.03
                      }
                    ]
                  }
                ],
                "note": "Daily, UTC. Read and click counts stop changing 7 days after a message is sent. cost is left out for accounts billed through a partner's credit line."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Templates"
        ],
        "operationId": "enableTemplateInsights",
        "summary": "Switch template insights on (cannot be undone)",
        "description": "Needs 'templates:manage' and {\"confirm\": true}. Adds link tracking and lets Meta collect anonymised chat data. WABA-wide: every number on this WhatsApp Business Account uses the same templates.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TemplateInsightsEnableRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Switched on.",
            "schema": {
              "$ref": "#/definitions/TemplateInsightsEnableResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t7ins",
                "enabled": true,
                "note": "Template insights are on for the whole WhatsApp Business Account, from now on (no data from before). This cannot be undone. Link tracking of a template's URL buttons can be turned off per template (cta_url_link_tracking_opted_out)."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTicketEvents",
        "summary": "The events, newest first",
        "description": "Scope: `tickets:manage`. The events of the number, newest first, each with its next date, how many tickets are sold and the lowest price. `status` filters by state, `archived=true` lists the archived ones instead, `q` searches the name, the slug and the code (EV-XXXXX). The rows have no `dates`, `types` or `problems`: GET /tickets/events/{id} has them. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only events in this state. Left out: all four.",
            "type": "string",
            "enum": [
              "draft",
              "published",
              "ended",
              "cancelled"
            ]
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "true: the archived events only. Left out: the ones that are not archived.",
            "type": "boolean"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search in the name, the slug or the EV- code (2 to 80 characters).",
            "type": "string",
            "x-example": "quiz"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The events.",
            "schema": {
              "$ref": "#/definitions/TicketEventsResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t1ev2",
                "events": [
                  {
                    "id": 12,
                    "slug": "summer-quiz",
                    "code": "EV-7H3KQ",
                    "name": "Summer Quiz",
                    "summary": "A night of questions on the terrace.",
                    "description": "",
                    "status": "published",
                    "sales": "on",
                    "visibility": "public",
                    "schedule": "single",
                    "seating": "none",
                    "archived": false,
                    "timezone": "Australia/Sydney",
                    "currency": "AUD",
                    "capacity": 120,
                    "held_back": 0,
                    "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz",
                    "cover_url": "",
                    "settings": {
                      "doors_min": 30,
                      "sales_end": "start",
                      "sales_end_min": 60,
                      "place": "venue",
                      "venue": {
                        "name": "The Terrace",
                        "address": "12 Harbour Street, Sydney",
                        "map": "",
                        "lat": 0,
                        "lng": 0,
                        "pin": false,
                        "note": "",
                        "hide_address": false
                      },
                      "online": {
                        "url": "",
                        "note": ""
                      },
                      "age": "",
                      "age_text": "",
                      "access_info": "",
                      "max_per_order": 10,
                      "max_per_buyer": 0,
                      "show_remaining": "low",
                      "fee": {
                        "ticket_minor": 0,
                        "order_minor": 0,
                        "show": "included"
                      },
                      "tax": {
                        "rate": 0,
                        "label": "VAT",
                        "inclusive": true
                      },
                      "donation": {
                        "enabled": false,
                        "amounts": []
                      },
                      "checkout": {
                        "email": "optional"
                      },
                      "names": "buyer",
                      "questions": [],
                      "terms_text": "",
                      "terms_url": "",
                      "marketing_optin": false,
                      "seat": {
                        "pick": "buyer",
                        "no_single": true
                      },
                      "reminders": [
                        1440
                      ],
                      "reminder_note": "",
                      "holder_changes": true,
                      "refund_policy": "none",
                      "refund_days": 7,
                      "refund_text": "",
                      "waitlist": "off",
                      "door": {
                        "opens_min": 120,
                        "reentry": "no",
                        "gates": [
                          {
                            "id": "g1",
                            "name": "Main entrance",
                            "type_ids": []
                          }
                        ]
                      },
                      "brand": {
                        "color": ""
                      },
                      "ticket_style": null
                    },
                    "from_price": 12.0,
                    "from_price_label": "A$12.00",
                    "tickets_sold": 86,
                    "dates_count": 1,
                    "next_date": {
                      "id": 31,
                      "event_id": 12,
                      "start": "2026-12-12T08:30:00.000Z",
                      "end": "2026-12-12T10:30:00.000Z",
                      "start_local": "2026-12-12T19:30",
                      "end_local": "2026-12-12T21:30",
                      "label": "",
                      "capacity": 120,
                      "sales": "on",
                      "status": "scheduled",
                      "sold": null,
                      "people": null,
                      "held": null,
                      "left": null,
                      "checked_in": null,
                      "sold_out": false,
                      "changed": null,
                      "cancelled": null
                    },
                    "seat_plan": null,
                    "sales_start": null,
                    "published": "2026-11-06T01:00:00.000Z",
                    "ended": null,
                    "cancelled": null,
                    "cancel_reason": "",
                    "created_by": "API key Zapier",
                    "created": "2026-11-06T01:00:00.000Z",
                    "updated": "2026-11-06T01:00:00.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "createTicketEvent",
        "summary": "Create an event as a draft with one date and one ticket type",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Makes a draft with one date and the ticket type General admission at `price` (0 or left out: free). `start` is local time in the number's time zone (2026-12-12T19:30) or ISO 8601 with an offset, and must be in the future. Time zone and currency start as the number's. Nothing is on sale until POST /tickets/events/{id}/publish. 409 `ticket_limit_reached` at 200 events. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketEventCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created.",
            "schema": {
              "$ref": "#/definitions/TicketEventResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t2ec3",
                "event": {
                  "id": 12,
                  "slug": "summer-quiz",
                  "code": "EV-7H3KQ",
                  "name": "Summer Quiz",
                  "summary": "",
                  "description": "",
                  "status": "draft",
                  "sales": "on",
                  "visibility": "public",
                  "schedule": "single",
                  "seating": "none",
                  "archived": false,
                  "timezone": "Australia/Sydney",
                  "currency": "AUD",
                  "capacity": 0,
                  "held_back": 0,
                  "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz",
                  "cover_url": "",
                  "settings": {
                    "doors_min": 0,
                    "sales_end": "start",
                    "sales_end_min": 60,
                    "place": "venue",
                    "venue": {
                      "name": "",
                      "address": "",
                      "map": "",
                      "lat": 0,
                      "lng": 0,
                      "pin": false,
                      "note": "",
                      "hide_address": false
                    },
                    "online": {
                      "url": "",
                      "note": ""
                    },
                    "age": "",
                    "age_text": "",
                    "access_info": "",
                    "max_per_order": 10,
                    "max_per_buyer": 0,
                    "show_remaining": "low",
                    "fee": {
                      "ticket_minor": 0,
                      "order_minor": 0,
                      "show": "included"
                    },
                    "tax": {
                      "rate": 0,
                      "label": "VAT",
                      "inclusive": true
                    },
                    "donation": {
                      "enabled": false,
                      "amounts": []
                    },
                    "checkout": {
                      "email": "optional"
                    },
                    "names": "buyer",
                    "questions": [],
                    "terms_text": "",
                    "terms_url": "",
                    "marketing_optin": false,
                    "seat": {
                      "pick": "buyer",
                      "no_single": true
                    },
                    "reminders": [
                      1440
                    ],
                    "reminder_note": "",
                    "holder_changes": true,
                    "refund_policy": "none",
                    "refund_days": 7,
                    "refund_text": "",
                    "waitlist": "off",
                    "door": {
                      "opens_min": 120,
                      "reentry": "no",
                      "gates": [
                        {
                          "id": "g1",
                          "name": "Main entrance",
                          "type_ids": []
                        }
                      ]
                    },
                    "brand": {
                      "color": ""
                    },
                    "ticket_style": null
                  },
                  "from_price": 12.0,
                  "from_price_label": "A$12.00",
                  "tickets_sold": 0,
                  "dates_count": 1,
                  "next_date": {
                    "id": 31,
                    "event_id": 12,
                    "start": "2026-12-12T08:30:00.000Z",
                    "end": "2026-12-12T10:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "end_local": "2026-12-12T21:30",
                    "label": "",
                    "capacity": null,
                    "sales": "on",
                    "status": "scheduled",
                    "sold": 0,
                    "people": 0,
                    "held": 0,
                    "left": null,
                    "checked_in": 0,
                    "sold_out": false,
                    "changed": null,
                    "cancelled": null
                  },
                  "seat_plan": null,
                  "sales_start": null,
                  "published": null,
                  "ended": null,
                  "cancelled": null,
                  "cancel_reason": "",
                  "created_by": "API key Zapier",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "dates": [
                    {
                      "id": 31,
                      "event_id": 12,
                      "start": "2026-12-12T08:30:00.000Z",
                      "end": "2026-12-12T10:30:00.000Z",
                      "start_local": "2026-12-12T19:30",
                      "end_local": "2026-12-12T21:30",
                      "label": "",
                      "capacity": null,
                      "sales": "on",
                      "status": "scheduled",
                      "sold": 0,
                      "people": 0,
                      "held": 0,
                      "left": null,
                      "checked_in": 0,
                      "sold_out": false,
                      "changed": null,
                      "cancelled": null
                    }
                  ],
                  "dates_more": false,
                  "types": [
                    {
                      "id": 44,
                      "event_id": 12,
                      "name": "General admission",
                      "description": "",
                      "role": "ticket",
                      "status": "active",
                      "visibility": "public",
                      "sort": 1,
                      "price_mode": "fixed",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "price_all_in": 12.0,
                      "price_all_in_label": "A$12.00",
                      "min_price": 0,
                      "admits": 1,
                      "quantity": 0,
                      "pool_id": 0,
                      "opens_after": 0,
                      "needs": 0,
                      "needs_each": false,
                      "min_per_order": 1,
                      "max_per_order": 0,
                      "sales_start": null,
                      "sales_end": null,
                      "sales_end_days": 0,
                      "date_ids": [],
                      "door_note": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ],
                  "problems": []
                },
                "note": "Created as a draft with one date and the ticket type General admission. Publish it when it is ready."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events/{id}": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicketEvent",
        "summary": "One event with its dates and ticket types",
        "description": "Scope: `tickets:manage`. By id, slug or code (EV-XXXXX). With its scheduled dates (soonest first, at most 50; `dates_more` says there are more, and GET /tickets/events/{id}/dates pages through all of them), its ticket types that are not archived and, for a draft, `problems`: what still stops publishing (empty: it can be published).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          }
        ],
        "responses": {
          "200": {
            "description": "The event.",
            "schema": {
              "$ref": "#/definitions/TicketEventResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t3eg4",
                "event": {
                  "id": 12,
                  "slug": "summer-quiz",
                  "code": "EV-7H3KQ",
                  "name": "Summer Quiz",
                  "summary": "A night of questions on the terrace.",
                  "description": "",
                  "status": "published",
                  "sales": "on",
                  "visibility": "public",
                  "schedule": "single",
                  "seating": "none",
                  "archived": false,
                  "timezone": "Australia/Sydney",
                  "currency": "AUD",
                  "capacity": 120,
                  "held_back": 0,
                  "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz",
                  "cover_url": "",
                  "settings": {
                    "doors_min": 30,
                    "sales_end": "start",
                    "sales_end_min": 60,
                    "place": "venue",
                    "venue": {
                      "name": "The Terrace",
                      "address": "12 Harbour Street, Sydney",
                      "map": "",
                      "lat": 0,
                      "lng": 0,
                      "pin": false,
                      "note": "",
                      "hide_address": false
                    },
                    "online": {
                      "url": "",
                      "note": ""
                    },
                    "age": "",
                    "age_text": "",
                    "access_info": "",
                    "max_per_order": 10,
                    "max_per_buyer": 0,
                    "show_remaining": "low",
                    "fee": {
                      "ticket_minor": 0,
                      "order_minor": 0,
                      "show": "included"
                    },
                    "tax": {
                      "rate": 0,
                      "label": "VAT",
                      "inclusive": true
                    },
                    "donation": {
                      "enabled": false,
                      "amounts": []
                    },
                    "checkout": {
                      "email": "optional"
                    },
                    "names": "buyer",
                    "questions": [],
                    "terms_text": "",
                    "terms_url": "",
                    "marketing_optin": false,
                    "seat": {
                      "pick": "buyer",
                      "no_single": true
                    },
                    "reminders": [
                      1440
                    ],
                    "reminder_note": "",
                    "holder_changes": true,
                    "refund_policy": "none",
                    "refund_days": 7,
                    "refund_text": "",
                    "waitlist": "off",
                    "door": {
                      "opens_min": 120,
                      "reentry": "no",
                      "gates": [
                        {
                          "id": "g1",
                          "name": "Main entrance",
                          "type_ids": []
                        }
                      ]
                    },
                    "brand": {
                      "color": ""
                    },
                    "ticket_style": null
                  },
                  "from_price": 12.0,
                  "from_price_label": "A$12.00",
                  "tickets_sold": 86,
                  "dates_count": 1,
                  "next_date": {
                    "id": 31,
                    "event_id": 12,
                    "start": "2026-12-12T08:30:00.000Z",
                    "end": "2026-12-12T10:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "end_local": "2026-12-12T21:30",
                    "label": "",
                    "capacity": 120,
                    "sales": "on",
                    "status": "scheduled",
                    "sold": 86,
                    "people": 86,
                    "held": 2,
                    "left": 32,
                    "checked_in": 0,
                    "sold_out": false,
                    "changed": null,
                    "cancelled": null
                  },
                  "seat_plan": null,
                  "sales_start": null,
                  "published": "2026-11-06T01:00:00.000Z",
                  "ended": null,
                  "cancelled": null,
                  "cancel_reason": "",
                  "created_by": "API key Zapier",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "dates": [
                    {
                      "id": 31,
                      "event_id": 12,
                      "start": "2026-12-12T08:30:00.000Z",
                      "end": "2026-12-12T10:30:00.000Z",
                      "start_local": "2026-12-12T19:30",
                      "end_local": "2026-12-12T21:30",
                      "label": "",
                      "capacity": 120,
                      "sales": "on",
                      "status": "scheduled",
                      "sold": 86,
                      "people": 86,
                      "held": 2,
                      "left": 32,
                      "checked_in": 0,
                      "sold_out": false,
                      "changed": null,
                      "cancelled": null
                    }
                  ],
                  "dates_more": false,
                  "types": [
                    {
                      "id": 44,
                      "event_id": 12,
                      "name": "Adult",
                      "description": "",
                      "role": "ticket",
                      "status": "active",
                      "visibility": "public",
                      "sort": 1,
                      "price_mode": "fixed",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "price_all_in": 12.0,
                      "price_all_in_label": "A$12.00",
                      "min_price": 0,
                      "admits": 1,
                      "quantity": 0,
                      "pool_id": 0,
                      "opens_after": 0,
                      "needs": 0,
                      "needs_each": false,
                      "min_per_order": 1,
                      "max_per_order": 0,
                      "sales_start": null,
                      "sales_end": null,
                      "sales_end_days": 0,
                      "date_ids": [],
                      "door_note": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "updateTicketEvent",
        "summary": "Change an event",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Send only the keys to change: `name`, `summary`, `description`, `visibility`, `sales` (on or paused), `capacity`, `held_back`, `timezone`, `currency` (refused once an order exists), `sales_start`, `slug` (until the first publish) and `settings` (merged key by key at the top level, then checked as a whole). `notify` true tells ticket holders when the venue changed. The status, the schedule, the seat plan and the pictures are changed on the dashboard: 400 `invalid_ticket_event` names a key that cannot be changed here. A capacity below what is sold is saved and `note` says so. 400 `nothing_to_change` without any of the keys. `ticket.event.sold_out` is sent when a lower limit makes a date full.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketEventPatchRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/TicketEventResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t4eu5",
                "event": {
                  "id": 12,
                  "slug": "summer-quiz",
                  "code": "EV-7H3KQ",
                  "name": "Summer Quiz",
                  "summary": "A night of questions on the terrace.",
                  "description": "",
                  "status": "published",
                  "sales": "paused",
                  "visibility": "public",
                  "schedule": "single",
                  "seating": "none",
                  "archived": false,
                  "timezone": "Australia/Sydney",
                  "currency": "AUD",
                  "capacity": 120,
                  "held_back": 0,
                  "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz",
                  "cover_url": "",
                  "settings": {
                    "doors_min": 30,
                    "sales_end": "start",
                    "sales_end_min": 60,
                    "place": "venue",
                    "venue": {
                      "name": "The Terrace",
                      "address": "12 Harbour Street, Sydney",
                      "map": "",
                      "lat": 0,
                      "lng": 0,
                      "pin": false,
                      "note": "",
                      "hide_address": false
                    },
                    "online": {
                      "url": "",
                      "note": ""
                    },
                    "age": "",
                    "age_text": "",
                    "access_info": "",
                    "max_per_order": 10,
                    "max_per_buyer": 0,
                    "show_remaining": "low",
                    "fee": {
                      "ticket_minor": 0,
                      "order_minor": 0,
                      "show": "included"
                    },
                    "tax": {
                      "rate": 0,
                      "label": "VAT",
                      "inclusive": true
                    },
                    "donation": {
                      "enabled": false,
                      "amounts": []
                    },
                    "checkout": {
                      "email": "optional"
                    },
                    "names": "buyer",
                    "questions": [],
                    "terms_text": "",
                    "terms_url": "",
                    "marketing_optin": false,
                    "seat": {
                      "pick": "buyer",
                      "no_single": true
                    },
                    "reminders": [
                      1440
                    ],
                    "reminder_note": "",
                    "holder_changes": true,
                    "refund_policy": "none",
                    "refund_days": 7,
                    "refund_text": "",
                    "waitlist": "off",
                    "door": {
                      "opens_min": 120,
                      "reentry": "no",
                      "gates": [
                        {
                          "id": "g1",
                          "name": "Main entrance",
                          "type_ids": []
                        }
                      ]
                    },
                    "brand": {
                      "color": ""
                    },
                    "ticket_style": null
                  },
                  "from_price": 12.0,
                  "from_price_label": "A$12.00",
                  "tickets_sold": 86,
                  "dates_count": 1,
                  "next_date": {
                    "id": 31,
                    "event_id": 12,
                    "start": "2026-12-12T08:30:00.000Z",
                    "end": "2026-12-12T10:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "end_local": "2026-12-12T21:30",
                    "label": "",
                    "capacity": 120,
                    "sales": "on",
                    "status": "scheduled",
                    "sold": 86,
                    "people": 86,
                    "held": 2,
                    "left": 32,
                    "checked_in": 0,
                    "sold_out": false,
                    "changed": null,
                    "cancelled": null
                  },
                  "seat_plan": null,
                  "sales_start": null,
                  "published": "2026-11-06T01:00:00.000Z",
                  "ended": null,
                  "cancelled": null,
                  "cancel_reason": "",
                  "created_by": "API key Zapier",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "dates": [
                    {
                      "id": 31,
                      "event_id": 12,
                      "start": "2026-12-12T08:30:00.000Z",
                      "end": "2026-12-12T10:30:00.000Z",
                      "start_local": "2026-12-12T19:30",
                      "end_local": "2026-12-12T21:30",
                      "label": "",
                      "capacity": 120,
                      "sales": "on",
                      "status": "scheduled",
                      "sold": 86,
                      "people": 86,
                      "held": 2,
                      "left": 32,
                      "checked_in": 0,
                      "sold_out": false,
                      "changed": null,
                      "cancelled": null
                    }
                  ],
                  "dates_more": false,
                  "types": [
                    {
                      "id": 44,
                      "event_id": 12,
                      "name": "Adult",
                      "description": "",
                      "role": "ticket",
                      "status": "active",
                      "visibility": "public",
                      "sort": 1,
                      "price_mode": "fixed",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "price_all_in": 12.0,
                      "price_all_in_label": "A$12.00",
                      "min_price": 0,
                      "admits": 1,
                      "quantity": 0,
                      "pool_id": 0,
                      "opens_after": 0,
                      "needs": 0,
                      "needs_each": false,
                      "min_per_order": 1,
                      "max_per_order": 0,
                      "sales_start": null,
                      "sales_end": null,
                      "sales_end_days": 0,
                      "date_ids": [],
                      "door_note": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                },
                "note": "Saved."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events/{id}/publish": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "publishTicketEvent",
        "summary": "Publish an event so tickets can be bought",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. No body. Puts the event on sale on its page (`url`) and in the WhatsApp chat. Needs ticket sales switched on for the number (403 `tickets_not_enabled`) and in its plan (403 `plan_not_allowed`). 409 `ticket_event_not_publishable` lists what is missing in `details.problems`. An event that is already published answers 200 and `note` says so.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          }
        ],
        "responses": {
          "200": {
            "description": "Published.",
            "schema": {
              "$ref": "#/definitions/TicketEventResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t5ep6",
                "event": {
                  "id": 12,
                  "slug": "summer-quiz",
                  "code": "EV-7H3KQ",
                  "name": "Summer Quiz",
                  "summary": "A night of questions on the terrace.",
                  "description": "",
                  "status": "published",
                  "sales": "on",
                  "visibility": "public",
                  "schedule": "single",
                  "seating": "none",
                  "archived": false,
                  "timezone": "Australia/Sydney",
                  "currency": "AUD",
                  "capacity": 120,
                  "held_back": 0,
                  "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz",
                  "cover_url": "",
                  "settings": {
                    "doors_min": 30,
                    "sales_end": "start",
                    "sales_end_min": 60,
                    "place": "venue",
                    "venue": {
                      "name": "The Terrace",
                      "address": "12 Harbour Street, Sydney",
                      "map": "",
                      "lat": 0,
                      "lng": 0,
                      "pin": false,
                      "note": "",
                      "hide_address": false
                    },
                    "online": {
                      "url": "",
                      "note": ""
                    },
                    "age": "",
                    "age_text": "",
                    "access_info": "",
                    "max_per_order": 10,
                    "max_per_buyer": 0,
                    "show_remaining": "low",
                    "fee": {
                      "ticket_minor": 0,
                      "order_minor": 0,
                      "show": "included"
                    },
                    "tax": {
                      "rate": 0,
                      "label": "VAT",
                      "inclusive": true
                    },
                    "donation": {
                      "enabled": false,
                      "amounts": []
                    },
                    "checkout": {
                      "email": "optional"
                    },
                    "names": "buyer",
                    "questions": [],
                    "terms_text": "",
                    "terms_url": "",
                    "marketing_optin": false,
                    "seat": {
                      "pick": "buyer",
                      "no_single": true
                    },
                    "reminders": [
                      1440
                    ],
                    "reminder_note": "",
                    "holder_changes": true,
                    "refund_policy": "none",
                    "refund_days": 7,
                    "refund_text": "",
                    "waitlist": "off",
                    "door": {
                      "opens_min": 120,
                      "reentry": "no",
                      "gates": [
                        {
                          "id": "g1",
                          "name": "Main entrance",
                          "type_ids": []
                        }
                      ]
                    },
                    "brand": {
                      "color": ""
                    },
                    "ticket_style": null
                  },
                  "from_price": 12.0,
                  "from_price_label": "A$12.00",
                  "tickets_sold": 86,
                  "dates_count": 1,
                  "next_date": {
                    "id": 31,
                    "event_id": 12,
                    "start": "2026-12-12T08:30:00.000Z",
                    "end": "2026-12-12T10:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "end_local": "2026-12-12T21:30",
                    "label": "",
                    "capacity": 120,
                    "sales": "on",
                    "status": "scheduled",
                    "sold": 86,
                    "people": 86,
                    "held": 2,
                    "left": 32,
                    "checked_in": 0,
                    "sold_out": false,
                    "changed": null,
                    "cancelled": null
                  },
                  "seat_plan": null,
                  "sales_start": null,
                  "published": "2026-11-06T01:00:00.000Z",
                  "ended": null,
                  "cancelled": null,
                  "cancel_reason": "",
                  "created_by": "API key Zapier",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "dates": [
                    {
                      "id": 31,
                      "event_id": 12,
                      "start": "2026-12-12T08:30:00.000Z",
                      "end": "2026-12-12T10:30:00.000Z",
                      "start_local": "2026-12-12T19:30",
                      "end_local": "2026-12-12T21:30",
                      "label": "",
                      "capacity": 120,
                      "sales": "on",
                      "status": "scheduled",
                      "sold": 86,
                      "people": 86,
                      "held": 2,
                      "left": 32,
                      "checked_in": 0,
                      "sold_out": false,
                      "changed": null,
                      "cancelled": null
                    }
                  ],
                  "dates_more": false,
                  "types": [
                    {
                      "id": 44,
                      "event_id": 12,
                      "name": "Adult",
                      "description": "",
                      "role": "ticket",
                      "status": "active",
                      "visibility": "public",
                      "sort": 1,
                      "price_mode": "fixed",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "price_all_in": 12.0,
                      "price_all_in_label": "A$12.00",
                      "min_price": 0,
                      "admits": 1,
                      "quantity": 0,
                      "pool_id": 0,
                      "opens_after": 0,
                      "needs": 0,
                      "needs_each": false,
                      "min_per_order": 1,
                      "max_per_order": 0,
                      "sales_start": null,
                      "sales_end": null,
                      "sales_end_days": 0,
                      "date_ids": [],
                      "door_note": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                },
                "note": "Published. Tickets can be bought at https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events/{id}/cancel": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "cancelTicketEvent",
        "summary": "Cancel an event and refund or void its tickets",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Cancels every scheduled date of the event. `refund` says what happens to the tickets: all = everything paid goes back, prices = the ticket prices without booking fees and donations, none = the tickets are voided and no money moves. `confirm` must be the word CANCEL. The answer comes at once (`started` true); the orders are refunded one by one in the background through the business's own payment provider, the ticket holders are told unless `notify` is false, `ticket.order.refunded` is sent for each order and `ticket.event.cancelled` for each date when it has finished. It cannot be undone. 409 `ticket_not_allowed` when the event is already cancelled or has ended. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketCancelRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled; the refunds run in the background.",
            "schema": {
              "$ref": "#/definitions/TicketEventResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t6ex7",
                "event": {
                  "id": 12,
                  "slug": "summer-quiz",
                  "code": "EV-7H3KQ",
                  "name": "Summer Quiz",
                  "summary": "A night of questions on the terrace.",
                  "description": "",
                  "status": "cancelled",
                  "sales": "on",
                  "visibility": "public",
                  "schedule": "single",
                  "seating": "none",
                  "archived": false,
                  "timezone": "Australia/Sydney",
                  "currency": "AUD",
                  "capacity": 120,
                  "held_back": 0,
                  "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz",
                  "cover_url": "",
                  "settings": {
                    "doors_min": 30,
                    "sales_end": "start",
                    "sales_end_min": 60,
                    "place": "venue",
                    "venue": {
                      "name": "The Terrace",
                      "address": "12 Harbour Street, Sydney",
                      "map": "",
                      "lat": 0,
                      "lng": 0,
                      "pin": false,
                      "note": "",
                      "hide_address": false
                    },
                    "online": {
                      "url": "",
                      "note": ""
                    },
                    "age": "",
                    "age_text": "",
                    "access_info": "",
                    "max_per_order": 10,
                    "max_per_buyer": 0,
                    "show_remaining": "low",
                    "fee": {
                      "ticket_minor": 0,
                      "order_minor": 0,
                      "show": "included"
                    },
                    "tax": {
                      "rate": 0,
                      "label": "VAT",
                      "inclusive": true
                    },
                    "donation": {
                      "enabled": false,
                      "amounts": []
                    },
                    "checkout": {
                      "email": "optional"
                    },
                    "names": "buyer",
                    "questions": [],
                    "terms_text": "",
                    "terms_url": "",
                    "marketing_optin": false,
                    "seat": {
                      "pick": "buyer",
                      "no_single": true
                    },
                    "reminders": [
                      1440
                    ],
                    "reminder_note": "",
                    "holder_changes": true,
                    "refund_policy": "none",
                    "refund_days": 7,
                    "refund_text": "",
                    "waitlist": "off",
                    "door": {
                      "opens_min": 120,
                      "reentry": "no",
                      "gates": [
                        {
                          "id": "g1",
                          "name": "Main entrance",
                          "type_ids": []
                        }
                      ]
                    },
                    "brand": {
                      "color": ""
                    },
                    "ticket_style": null
                  },
                  "from_price": 12.0,
                  "from_price_label": "A$12.00",
                  "tickets_sold": 86,
                  "dates_count": 0,
                  "next_date": null,
                  "seat_plan": null,
                  "sales_start": null,
                  "published": "2026-11-06T01:00:00.000Z",
                  "ended": null,
                  "cancelled": "2026-11-06T01:00:00.000Z",
                  "cancel_reason": "The venue is closed",
                  "created_by": "API key Zapier",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "dates": [],
                  "dates_more": false,
                  "types": [
                    {
                      "id": 44,
                      "event_id": 12,
                      "name": "Adult",
                      "description": "",
                      "role": "ticket",
                      "status": "active",
                      "visibility": "public",
                      "sort": 1,
                      "price_mode": "fixed",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "price_all_in": 12.0,
                      "price_all_in_label": "A$12.00",
                      "min_price": 0,
                      "admits": 1,
                      "quantity": 0,
                      "pool_id": 0,
                      "opens_after": 0,
                      "needs": 0,
                      "needs_each": false,
                      "min_per_order": 1,
                      "max_per_order": 0,
                      "sales_start": null,
                      "sales_end": null,
                      "sales_end_days": 0,
                      "date_ids": [],
                      "door_note": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                },
                "started": true,
                "note": "Cancelled. Orders are refunded one by one in the background; ticket.event.cancelled is sent for each date when it has finished."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events/{id}/dates": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTicketDates",
        "summary": "The dates of an event with what is sold and left",
        "description": "Scope: `tickets:manage`. The dates of an event, soonest first, each with what is sold, held in baskets, left and checked in. `status` is scheduled (the default), ended, cancelled or all; `from` and `to` are days (YYYY-MM-DD in the event's time zone) or ISO 8601 times. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Default scheduled.",
            "type": "string",
            "enum": [
              "scheduled",
              "ended",
              "cancelled",
              "all"
            ],
            "default": "scheduled"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Dates that start on or after this day (YYYY-MM-DD in the event's time zone) or ISO 8601 time.",
            "type": "string",
            "x-example": "2026-12-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Dates that start up to this day (included) or ISO 8601 time.",
            "type": "string",
            "x-example": "2026-12-31"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The dates.",
            "schema": {
              "$ref": "#/definitions/TicketDatesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t7dl8",
                "dates": [
                  {
                    "id": 31,
                    "event_id": 12,
                    "start": "2026-12-12T08:30:00.000Z",
                    "end": "2026-12-12T10:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "end_local": "2026-12-12T21:30",
                    "label": "",
                    "capacity": 120,
                    "sales": "on",
                    "status": "scheduled",
                    "sold": 86,
                    "people": 86,
                    "held": 2,
                    "left": 32,
                    "checked_in": 0,
                    "sold_out": false,
                    "changed": null,
                    "cancelled": null
                  }
                ],
                "next_cursor": null,
                "count": 1,
                "timezone": "Australia/Sydney"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "createTicketDate",
        "summary": "Add a date to an event",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. `start` is local time in the event's time zone or ISO 8601 with an offset, in the future. `end` defaults to 120 minutes after `start` (it must be after it, at most 31 days later). `capacity`: -1 = the event's (the default), 0 = no limit, else people. 409 `ticket_limit_reached` at 400 scheduled dates; 409 `ticket_not_allowed` when the event is cancelled; 400 `invalid_ticket_event` when the event already has a date at that time. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketDateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Added.",
            "schema": {
              "$ref": "#/definitions/TicketDateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t8dc9",
                "date": {
                  "id": 32,
                  "event_id": 12,
                  "start": "2026-12-19T08:30:00.000Z",
                  "end": "2026-12-19T10:30:00.000Z",
                  "start_local": "2026-12-19T19:30",
                  "end_local": "2026-12-19T21:30",
                  "label": "Late show",
                  "capacity": 120,
                  "sales": "on",
                  "status": "scheduled",
                  "sold": 0,
                  "people": 0,
                  "held": 0,
                  "left": 120,
                  "checked_in": 0,
                  "sold_out": false,
                  "changed": null,
                  "cancelled": null
                },
                "note": "Added."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/dates/{date_id}": {
      "patch": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "updateTicketDate",
        "summary": "Change a date: time, label, capacity, sales on or paused",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Send only the keys to change: `start`, `end`, `label`, `capacity`, `sales` (on or paused). `notify` true tells the ticket holders about a new time, on WhatsApp or by email. A date with valid tickets cannot be moved into the past. 400 `nothing_to_change` without any of the keys. `ticket.event.sold_out` is sent when a lower limit makes a date full.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "date_id",
            "in": "path",
            "required": true,
            "description": "The date's id.",
            "type": "string",
            "x-example": "31"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketDateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/TicketDateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t9du1",
                "date": {
                  "id": 31,
                  "event_id": 12,
                  "start": "2026-12-12T09:00:00.000Z",
                  "end": "2026-12-12T11:00:00.000Z",
                  "start_local": "2026-12-12T20:00",
                  "end_local": "2026-12-12T22:00",
                  "label": "",
                  "capacity": 120,
                  "sales": "on",
                  "status": "scheduled",
                  "sold": 86,
                  "people": 86,
                  "held": 2,
                  "left": 32,
                  "checked_in": 0,
                  "sold_out": false,
                  "changed": "2026-11-06T01:00:00.000Z",
                  "cancelled": null
                },
                "note": "Saved. Ticket holders were told."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/dates/{date_id}/cancel": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "cancelTicketDate",
        "summary": "Cancel one date and refund or void its tickets",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Cancels this one date; the other dates of the event go on. `refund`: all = everything paid goes back, prices = the ticket prices without booking fees and donations, none = the tickets are voided and no money moves. `confirm` must be the word CANCEL. The answer comes at once (`started` true); the orders are refunded one by one in the background, the ticket holders are told unless `notify` is false, `ticket.order.refunded` is sent for each order and `ticket.event.cancelled` when it has finished. It cannot be undone. 409 `ticket_not_allowed` when the date is already cancelled or has ended. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "date_id",
            "in": "path",
            "required": true,
            "description": "The date's id.",
            "type": "string",
            "x-example": "31"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketCancelRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled; the refunds run in the background.",
            "schema": {
              "$ref": "#/definitions/TicketDateResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t1dx2",
                "date": {
                  "id": 31,
                  "event_id": 12,
                  "start": "2026-12-12T08:30:00.000Z",
                  "end": "2026-12-12T10:30:00.000Z",
                  "start_local": "2026-12-12T19:30",
                  "end_local": "2026-12-12T21:30",
                  "label": "",
                  "capacity": 120,
                  "sales": "on",
                  "status": "cancelled",
                  "sold": 86,
                  "people": 86,
                  "held": 2,
                  "left": 32,
                  "checked_in": 0,
                  "sold_out": false,
                  "changed": null,
                  "cancelled": "2026-11-06T01:00:00.000Z"
                },
                "started": true,
                "note": "Cancelled. Orders are refunded one by one in the background; ticket.event.cancelled is sent for each date when it has finished."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/dates/{date_id}/door": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicketDoorList",
        "summary": "The door list of a date for your own scanner",
        "description": "Scope: `tickets:manage`. For a scanner of your own. Each ticket of the date comes with `code_sha256`, the lower-case hex SHA-256 of the text in its QR code: hash what you scan and look it up, so the codes themselves never leave app2email. No contact, email or money is in the list. The first calls page through the date (while `more` is true, send `cursor` as `since`); later the same call with the last `cursor` answers only what changed, and `gone` lists the ids that are no longer tickets of this date. Record an admission with POST /tickets/check-ins.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "date_id",
            "in": "path",
            "required": true,
            "description": "The date's id.",
            "type": "string",
            "x-example": "31"
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "The cursor of an earlier answer. Left out: from the start.",
            "type": "string",
            "x-example": "u1793926800000000.502"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 2000, default 2000).",
            "type": "integer",
            "minimum": 1,
            "maximum": 2000,
            "default": 2000
          }
        ],
        "responses": {
          "200": {
            "description": "The door list.",
            "schema": {
              "$ref": "#/definitions/TicketDoorList"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t2dd3",
                "date": {
                  "id": 31,
                  "event_id": 12,
                  "start": "2026-12-12T08:30:00.000Z",
                  "end": "2026-12-12T10:30:00.000Z",
                  "start_local": "2026-12-12T19:30",
                  "end_local": "2026-12-12T21:30",
                  "label": "",
                  "capacity": 120,
                  "sales": "on",
                  "status": "scheduled",
                  "sold": null,
                  "people": null,
                  "held": null,
                  "left": null,
                  "checked_in": null,
                  "sold_out": false,
                  "changed": null,
                  "cancelled": null
                },
                "counts": {
                  "sold": 86,
                  "in": 0,
                  "to_come": 86
                },
                "tickets": [
                  {
                    "id": 501,
                    "code_sha256": "5f1d0c4b8e2a7936d1c0b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4",
                    "status": "valid",
                    "type_id": 44,
                    "type_name": "Adult",
                    "role": "ticket",
                    "holder_name": "John Smith",
                    "seat_label": "",
                    "admits": 1,
                    "check_in": {
                      "people": 0,
                      "inside": 0,
                      "entries": 0,
                      "first_at": null,
                      "last_at": null,
                      "last_out_at": null,
                      "gate": ""
                    },
                    "door_note": "",
                    "id_check": "",
                    "order_reference": "TK-7H3KQ9",
                    "passed_on": false,
                    "answers": []
                  }
                ],
                "gone": [],
                "cursor": "u1793926800000000.501",
                "more": false,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events/{id}/types": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTicketTypes",
        "summary": "The ticket types and extras of an event",
        "description": "Scope: `tickets:manage`. The ticket types and the extras (role addon) of an event, in their order, with the price as typed and the all-in price a buyer pays. `archived=true` includes the archived ones.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "true: include the archived ticket types.",
            "type": "boolean"
          }
        ],
        "responses": {
          "200": {
            "description": "The ticket types.",
            "schema": {
              "$ref": "#/definitions/TicketTypesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t3tl4",
                "types": [
                  {
                    "id": 44,
                    "event_id": 12,
                    "name": "Adult",
                    "description": "",
                    "role": "ticket",
                    "status": "active",
                    "visibility": "public",
                    "sort": 1,
                    "price_mode": "fixed",
                    "price": 12.0,
                    "price_label": "A$12.00",
                    "price_all_in": 12.0,
                    "price_all_in_label": "A$12.00",
                    "min_price": 0,
                    "admits": 1,
                    "quantity": 0,
                    "pool_id": 0,
                    "opens_after": 0,
                    "needs": 0,
                    "needs_each": false,
                    "min_per_order": 1,
                    "max_per_order": 0,
                    "sales_start": null,
                    "sales_end": null,
                    "sales_end_days": 0,
                    "date_ids": [],
                    "door_note": "",
                    "created": "2026-11-06T01:00:00.000Z",
                    "updated": "2026-11-06T01:00:00.000Z"
                  }
                ],
                "currency": "AUD"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "createTicketType",
        "summary": "Add a ticket type or an extra to an event",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. `name` is needed; everything else has a default (a free ticket that admits one person and has no limit of its own). `role` addon makes an extra such as parking, bought together with a ticket. `price_mode` choose lets the buyer name the amount, from `min_price`. `pool_id`, `opens_after` and `needs` point at a pool or another ticket type of the same event (0 = none). 409 `ticket_limit_reached` at 40 ticket types. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketTypeRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Added.",
            "schema": {
              "$ref": "#/definitions/TicketTypeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t4tc5",
                "type": {
                  "id": 45,
                  "event_id": 12,
                  "name": "Child",
                  "description": "",
                  "role": "ticket",
                  "status": "active",
                  "visibility": "public",
                  "sort": 2,
                  "price_mode": "fixed",
                  "price": 6.0,
                  "price_label": "A$6.00",
                  "price_all_in": 6.0,
                  "price_all_in_label": "A$6.00",
                  "min_price": 0,
                  "admits": 1,
                  "quantity": 0,
                  "pool_id": 0,
                  "opens_after": 0,
                  "needs": 0,
                  "needs_each": false,
                  "min_per_order": 1,
                  "max_per_order": 0,
                  "sales_start": null,
                  "sales_end": null,
                  "sales_end_days": 0,
                  "date_ids": [],
                  "door_note": "",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                },
                "note": "Added."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/types/{type_id}": {
      "patch": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "updateTicketType",
        "summary": "Change or archive a ticket type",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Send only the keys to change. `status` archived takes the ticket type off sale everywhere, at any time (the tickets sold stay valid); back to active is refused with 409 `ticket_limit_reached` while the event has 40 active ticket types. A ticket type on a seat plan is linked to its seat category on the dashboard, not here. 400 `nothing_to_change` without any key. `ticket.event.sold_out` is sent when a lower limit makes a date full.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "type_id",
            "in": "path",
            "required": true,
            "description": "The ticket type's id.",
            "type": "string",
            "x-example": "44"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketTypeRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/TicketTypeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t5tu6",
                "type": {
                  "id": 44,
                  "event_id": 12,
                  "name": "Adult",
                  "description": "",
                  "role": "ticket",
                  "status": "active",
                  "visibility": "public",
                  "sort": 1,
                  "price_mode": "fixed",
                  "price": 14.0,
                  "price_label": "A$14.00",
                  "price_all_in": 14.0,
                  "price_all_in_label": "A$14.00",
                  "min_price": 0,
                  "admits": 1,
                  "quantity": 80,
                  "pool_id": 0,
                  "opens_after": 0,
                  "needs": 0,
                  "needs_each": false,
                  "min_per_order": 1,
                  "max_per_order": 0,
                  "sales_start": null,
                  "sales_end": null,
                  "sales_end_days": 0,
                  "date_ids": [],
                  "door_note": "",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                },
                "note": "Saved."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/events/{id}/availability": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicketAvailability",
        "summary": "What is on sale and how many are left for a date",
        "description": "Scope: `tickets:manage`. For one date of an event: `on_sale` (buyers can buy now), `closed` (cancelled or ended when the date takes no order from anyone), `sold_out`, and every active ticket type with its `state` as a buyer meets it, how many are `left` (null: nothing limits it), the most one order may take (`max`) and the all-in price. `date_id` is needed when the event has several scheduled dates (400 `invalid_ticket_event` without it). Buyers buy on the event's `url`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event: its id, its slug (eg summer-quiz) or its code (EV-XXXXX).",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "date_id",
            "in": "query",
            "required": false,
            "description": "The date's id. Needed when the event has more than one scheduled date.",
            "type": "integer",
            "x-example": 31
          }
        ],
        "responses": {
          "200": {
            "description": "What is on sale.",
            "schema": {
              "$ref": "#/definitions/TicketAvailability"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t6av7",
                "event": {
                  "id": 12,
                  "name": "Summer Quiz",
                  "slug": "summer-quiz",
                  "status": "published",
                  "sales": "on",
                  "currency": "AUD",
                  "url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7/summer-quiz"
                },
                "date": {
                  "id": 31,
                  "event_id": 12,
                  "start": "2026-12-12T08:30:00.000Z",
                  "end": "2026-12-12T10:30:00.000Z",
                  "start_local": "2026-12-12T19:30",
                  "end_local": "2026-12-12T21:30",
                  "label": "",
                  "capacity": 120,
                  "sales": "on",
                  "status": "scheduled",
                  "sold": 86,
                  "people": 86,
                  "held": 2,
                  "left": 32,
                  "checked_in": 0,
                  "sold_out": false,
                  "changed": null,
                  "cancelled": null
                },
                "on_sale": true,
                "closed": "",
                "sold_out": false,
                "max_per_order": 10,
                "types": [
                  {
                    "type_id": 44,
                    "name": "Adult",
                    "role": "ticket",
                    "visibility": "public",
                    "state": "on_sale",
                    "left": 32,
                    "max": 10,
                    "price": 12.0,
                    "price_label": "A$12.00",
                    "sales_end": "2026-12-12T08:30:00.000Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/orders": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTicketOrders",
        "summary": "The ticket orders, newest first",
        "description": "Scope: `tickets:manage`. Newest first. Left out, `status` gives every order except the unfinished checkouts (pending and expired). Find a buyer's orders with `contact`, `email` or `q` (the reference, the buyer's or a holder's name, a seat label, a promo code). `from` and `to` filter by the day the order was made; `attention=true` gives the orders that need a look (a failed or disputed payment, a refund that does not add up); `tickets=true` adds each order's tickets. `page_url` opens the tickets without a login: give it only to the buyer. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "event_id",
            "in": "query",
            "required": false,
            "description": "Only orders of this event (its id).",
            "type": "integer",
            "x-example": 12
          },
          {
            "name": "date_id",
            "in": "query",
            "required": false,
            "description": "Only orders for this date (its id).",
            "type": "integer",
            "x-example": 31
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only orders in this state. Left out: every state except pending and expired.",
            "type": "string",
            "enum": [
              "pending",
              "confirmed",
              "partly_refunded",
              "refunded",
              "cancelled",
              "expired"
            ]
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "online: paid by card. free: a free order. comp: complimentary. outside: paid outside.",
            "type": "string",
            "enum": [
              "online",
              "free",
              "comp",
              "outside"
            ]
          },
          {
            "name": "contact",
            "in": "query",
            "required": false,
            "description": "The buyer: a WhatsApp number with country code, digits only, or a business-scoped user id.",
            "type": "string",
            "x-example": "61412345678"
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "The buyer's email address.",
            "type": "string"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search in the reference, the buyer's or a holder's name, a seat label or a promo code (2 to 80 characters).",
            "type": "string"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Orders made from this day (YYYY-MM-DD in the number's time zone) or ISO 8601 time.",
            "type": "string",
            "x-example": "2026-11-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Orders made up to this day (included) or ISO 8601 time.",
            "type": "string",
            "x-example": "2026-11-30"
          },
          {
            "name": "attention",
            "in": "query",
            "required": false,
            "description": "true: only orders that need a look.",
            "type": "boolean"
          },
          {
            "name": "tickets",
            "in": "query",
            "required": false,
            "description": "true: each order carries its tickets.",
            "type": "boolean"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The orders.",
            "schema": {
              "$ref": "#/definitions/TicketOrdersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t7ol8",
                "orders": [
                  {
                    "id": 8812,
                    "reference": "TK-7H3KQ9",
                    "status": "confirmed",
                    "kind": "comp",
                    "channel": "api",
                    "source": "",
                    "event": {
                      "id": 12,
                      "name": "Summer Quiz",
                      "slug": "summer-quiz"
                    },
                    "date": {
                      "id": 31,
                      "start": "2026-12-12T08:30:00.000Z",
                      "start_local": "2026-12-12T19:30",
                      "label": ""
                    },
                    "buyer": {
                      "name": "John Smith",
                      "contact": "61412345678",
                      "email": "",
                      "no_whatsapp": false
                    },
                    "currency": "AUD",
                    "total": 0,
                    "total_label": "A$0.00",
                    "tickets_total": 0,
                    "order_fee": 0,
                    "donation": 0,
                    "discount": 24.0,
                    "fees": 0,
                    "tax": 0,
                    "refunded": 0,
                    "refunded_label": "",
                    "ticket_count": 2,
                    "people_count": 2,
                    "addon_count": 0,
                    "promo_code": "",
                    "payment": {
                      "id": null,
                      "method": "",
                      "note": ""
                    },
                    "comp_reason": "guest",
                    "staff_note": "",
                    "created_by": "API key Zapier",
                    "attention": "",
                    "close_reason": "",
                    "refund_request": null,
                    "answers": {},
                    "marketing_optin": false,
                    "erased": false,
                    "page_url": "https://www.app2email.com/t/oq3k7m2xw5ya4n6bt2hc7r5dz3ef",
                    "expires": null,
                    "confirmed": "2026-11-06T01:00:00.000Z",
                    "cancelled": null,
                    "refunded_at": null,
                    "created": "2026-11-06T01:00:00.000Z",
                    "updated": "2026-11-06T01:00:00.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "createTicketOrder",
        "summary": "Issue complimentary tickets or record a sale paid outside",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Issues the tickets at once and never takes money: `kind` comp makes complimentary tickets (every price 0), `kind` outside records a sale that was paid outside app2email (cash, a bank transfer, a card machine) at the ticket prices. `items` names the ticket types and quantities; on an event with a seat plan the best free seats are taken unless `seat_keys` names them. Unless `notify` is false the buyer gets the tickets on WhatsApp (when `buyer.contact` is given) and by email (when `buyer.email` is given); with neither, share `order.page_url` yourself. `check_in_now` checks every ticket in at once (a sale at the door). `ticket.order.confirmed` is sent. Sales windows and hidden ticket types do not bind an order made here; the places kept for the door stay kept. 409 `tickets_sold_out` when there is no room, 409 `tickets_not_on_sale` for a date that is cancelled or over, 403 `tickets_not_enabled` while ticket sales are switched off. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketOrderCreateRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Issued.",
            "schema": {
              "$ref": "#/definitions/TicketOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t8oc9",
                "order": {
                  "id": 8812,
                  "reference": "TK-7H3KQ9",
                  "status": "confirmed",
                  "kind": "comp",
                  "channel": "api",
                  "source": "",
                  "event": {
                    "id": 12,
                    "name": "Summer Quiz",
                    "slug": "summer-quiz"
                  },
                  "date": {
                    "id": 31,
                    "start": "2026-12-12T08:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "label": ""
                  },
                  "buyer": {
                    "name": "John Smith",
                    "contact": "61412345678",
                    "email": "",
                    "no_whatsapp": false
                  },
                  "currency": "AUD",
                  "total": 0,
                  "total_label": "A$0.00",
                  "tickets_total": 0,
                  "order_fee": 0,
                  "donation": 0,
                  "discount": 24.0,
                  "fees": 0,
                  "tax": 0,
                  "refunded": 0,
                  "refunded_label": "",
                  "ticket_count": 2,
                  "people_count": 2,
                  "addon_count": 0,
                  "promo_code": "",
                  "payment": {
                    "id": null,
                    "method": "",
                    "note": ""
                  },
                  "comp_reason": "guest",
                  "staff_note": "",
                  "created_by": "API key Zapier",
                  "attention": "",
                  "close_reason": "",
                  "refund_request": null,
                  "answers": {},
                  "marketing_optin": false,
                  "erased": false,
                  "page_url": "https://www.app2email.com/t/oq3k7m2xw5ya4n6bt2hc7r5dz3ef",
                  "expires": null,
                  "confirmed": "2026-11-06T01:00:00.000Z",
                  "cancelled": null,
                  "refunded_at": null,
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "tickets": [
                    {
                      "id": 501,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 1,
                      "status": "valid",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 0,
                      "price_label": "A$0.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    },
                    {
                      "id": 502,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 2,
                      "status": "valid",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 0,
                      "price_label": "A$0.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "https://www.app2email.com/t/kb7m4q2xr6ta3n5wz2hc4d7ey5gj",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                },
                "sent": true,
                "note": "Issued 2 tickets. The buyer gets them on WhatsApp."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/orders/{id}": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicketOrder",
        "summary": "One order with its tickets, by id or reference",
        "description": "Scope: `tickets:manage`. By id or reference (TK-XXXXXX). The order with its money, the buyer and every ticket with its status and check-in state. `page_url` (on the order and on each valid ticket) opens the tickets without a login: treat it like a password and give it only to the buyer.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order: its id or its reference (TK-XXXXXX).",
            "type": "string",
            "x-example": "TK-7H3KQ9"
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "schema": {
              "$ref": "#/definitions/TicketOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t9og1",
                "order": {
                  "id": 8812,
                  "reference": "TK-7H3KQ9",
                  "status": "confirmed",
                  "kind": "comp",
                  "channel": "api",
                  "source": "",
                  "event": {
                    "id": 12,
                    "name": "Summer Quiz",
                    "slug": "summer-quiz"
                  },
                  "date": {
                    "id": 31,
                    "start": "2026-12-12T08:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "label": ""
                  },
                  "buyer": {
                    "name": "John Smith",
                    "contact": "61412345678",
                    "email": "",
                    "no_whatsapp": false
                  },
                  "currency": "AUD",
                  "total": 0,
                  "total_label": "A$0.00",
                  "tickets_total": 0,
                  "order_fee": 0,
                  "donation": 0,
                  "discount": 24.0,
                  "fees": 0,
                  "tax": 0,
                  "refunded": 0,
                  "refunded_label": "",
                  "ticket_count": 2,
                  "people_count": 2,
                  "addon_count": 0,
                  "promo_code": "",
                  "payment": {
                    "id": null,
                    "method": "",
                    "note": ""
                  },
                  "comp_reason": "guest",
                  "staff_note": "",
                  "created_by": "API key Zapier",
                  "attention": "",
                  "close_reason": "",
                  "refund_request": null,
                  "answers": {},
                  "marketing_optin": false,
                  "erased": false,
                  "page_url": "https://www.app2email.com/t/oq3k7m2xw5ya4n6bt2hc7r5dz3ef",
                  "expires": null,
                  "confirmed": "2026-11-06T01:00:00.000Z",
                  "cancelled": null,
                  "refunded_at": null,
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "tickets": [
                    {
                      "id": 501,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 1,
                      "status": "valid",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 0,
                      "price_label": "A$0.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    },
                    {
                      "id": 502,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 2,
                      "status": "valid",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 0,
                      "price_label": "A$0.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "https://www.app2email.com/t/kb7m4q2xr6ta3n5wz2hc4d7ey5gj",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/orders/{id}/refund": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "refundTicketOrder",
        "summary": "Refund an order or some of its tickets",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Refunds every valid ticket of the order, or only `ticket_ids`. `what`: all (the default) or prices (without booking fees and donations). `money` says how the money goes back: provider = through the business's own Stripe or PayPal account (real money, it cannot be undone), recorded = it was handed back outside, outside = the business refunded it at Stripe or PayPal itself, none = cancel without a refund. Left out, it follows the order: provider for an online order, recorded for a sale paid outside, none for free and complimentary tickets. The refunded tickets stop working at once and their places go back on sale; the buyer is told unless `notify` is false. `ticket.order.refunded` is sent. 409 `refund_not_possible` when nothing is left to refund, 409 `payments_not_connected`, 502 `payment_provider_error`. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order: its id or its reference (TK-XXXXXX).",
            "type": "string",
            "x-example": "TK-7H3KQ9"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/TicketRefundRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Refunded.",
            "schema": {
              "$ref": "#/definitions/TicketOrderResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t1or2",
                "order": {
                  "id": 8812,
                  "reference": "TK-7H3KQ9",
                  "status": "partly_refunded",
                  "kind": "online",
                  "channel": "web",
                  "source": "",
                  "event": {
                    "id": 12,
                    "name": "Summer Quiz",
                    "slug": "summer-quiz"
                  },
                  "date": {
                    "id": 31,
                    "start": "2026-12-12T08:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "label": ""
                  },
                  "buyer": {
                    "name": "John Smith",
                    "contact": "61412345678",
                    "email": "",
                    "no_whatsapp": false
                  },
                  "currency": "AUD",
                  "total": 24.0,
                  "total_label": "A$24.00",
                  "tickets_total": 24.0,
                  "order_fee": 0,
                  "donation": 0,
                  "discount": 0,
                  "fees": 0,
                  "tax": 0,
                  "refunded": 12.0,
                  "refunded_label": "A$12.00",
                  "ticket_count": 2,
                  "people_count": 2,
                  "addon_count": 0,
                  "promo_code": "",
                  "payment": {
                    "id": 15,
                    "method": "stripe",
                    "note": ""
                  },
                  "comp_reason": "",
                  "staff_note": "",
                  "created_by": "customer",
                  "attention": "",
                  "close_reason": "",
                  "refund_request": null,
                  "answers": {},
                  "marketing_optin": false,
                  "erased": false,
                  "page_url": "https://www.app2email.com/t/oq3k7m2xw5ya4n6bt2hc7r5dz3ef",
                  "expires": null,
                  "confirmed": "2026-11-06T01:00:00.000Z",
                  "cancelled": null,
                  "refunded_at": "2026-11-06T01:00:00.000Z",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "tickets": [
                    {
                      "id": 501,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 1,
                      "status": "valid",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    },
                    {
                      "id": 502,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 2,
                      "status": "refunded",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 12.0,
                      "price_label": "A$12.00",
                      "face": 12.0,
                      "refunded": 12.0,
                      "refunded_at": "2026-11-06T01:00:00.000Z",
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                },
                "refunded": 12.0,
                "refunded_label": "A$12.00",
                "note": "Refunded A$12.00 through Stripe. The tickets are no longer valid."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/orders/{id}/resend": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "resendTicketOrder",
        "summary": "Send the buyer their tickets again",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. No body. The buyer gets the tickets again: a WhatsApp message (inside their 24 hour window, else a template) when the order has a number, and an email when it has an address. `sent` lists what happened per channel. 409 `ticket_not_allowed` when the order has no valid ticket, or neither a WhatsApp number nor an email address. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order: its id or its reference (TK-XXXXXX).",
            "type": "string",
            "x-example": "TK-7H3KQ9"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          }
        ],
        "responses": {
          "200": {
            "description": "Sent.",
            "schema": {
              "$ref": "#/definitions/TicketResendResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t2os3",
                "sent": [
                  {
                    "channel": "whatsapp",
                    "result": "sent",
                    "detail": ""
                  }
                ],
                "note": "Sent again."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/issued": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTickets",
        "summary": "The tickets (attendees) with their check-in state",
        "description": "Scope: `tickets:manage`. One row per ticket, by id, with the holder, the seat, the price, the check-in state and the buyer. `event_id`, `date_id` or `order` is needed (400 `invalid_ticket_order` without one). Left out, `status` gives the valid and the blocked tickets and `role` the admission tickets (addon: the extras, all: both). `checked_in=true` gives who is in, `checked_in=false` who has not come yet. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "event_id",
            "in": "query",
            "required": false,
            "description": "The tickets of this event (its id).",
            "type": "integer",
            "x-example": 12
          },
          {
            "name": "date_id",
            "in": "query",
            "required": false,
            "description": "The tickets of this date (its id).",
            "type": "integer",
            "x-example": 31
          },
          {
            "name": "type_id",
            "in": "query",
            "required": false,
            "description": "Only this ticket type (its id).",
            "type": "integer"
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "The tickets of this order: its id or its reference (TK-XXXXXX).",
            "type": "string",
            "x-example": "TK-7H3KQ9"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only tickets in this state. Left out: valid and blocked.",
            "type": "string",
            "enum": [
              "valid",
              "blocked",
              "refunded",
              "cancelled",
              "transferred"
            ]
          },
          {
            "name": "checked_in",
            "in": "query",
            "required": false,
            "description": "true: only tickets that were used at the door. false: only the ones that were not.",
            "type": "boolean"
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Default ticket.",
            "type": "string",
            "enum": [
              "ticket",
              "addon",
              "all"
            ],
            "default": "ticket"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search in the holder's or the buyer's name, the reference or a seat label (2 to 80 characters).",
            "type": "string"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The tickets.",
            "schema": {
              "$ref": "#/definitions/TicketsIssuedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t3il4",
                "tickets": [
                  {
                    "id": 501,
                    "order_id": 8812,
                    "order_reference": "TK-7H3KQ9",
                    "event_id": 12,
                    "date_id": 31,
                    "type_id": 44,
                    "type_name": "Adult",
                    "role": "ticket",
                    "seq": 1,
                    "status": "valid",
                    "holder_name": "John Smith",
                    "answers": {},
                    "seat": null,
                    "admits": 1,
                    "check_in": {
                      "people": 0,
                      "inside": 0,
                      "entries": 0,
                      "first_at": null,
                      "last_at": null,
                      "last_out_at": null,
                      "gate": ""
                    },
                    "currency": "AUD",
                    "price": 0,
                    "price_label": "A$0.00",
                    "face": 12.0,
                    "refunded": 0,
                    "refunded_at": null,
                    "block_reason": "",
                    "passed_on": false,
                    "replaces_id": 0,
                    "replaced_by_id": 0,
                    "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                    "created": "2026-11-06T01:00:00.000Z",
                    "updated": "2026-11-06T01:00:00.000Z",
                    "buyer": {
                      "name": "John Smith",
                      "contact": "61412345678",
                      "email": ""
                    }
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/issued/{id}": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicket",
        "summary": "One ticket",
        "description": "Scope: `tickets:manage`. By its id (digits). The text of a ticket's QR code is never accepted in an address: POST /tickets/check-ins takes it. The answer also has the order's id, reference, status and buyer.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ticket's id (digits). The text of a ticket's QR code is never accepted in an address.",
            "type": "string",
            "x-example": "501"
          }
        ],
        "responses": {
          "200": {
            "description": "The ticket.",
            "schema": {
              "$ref": "#/definitions/TicketIssuedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t4ig5",
                "ticket": {
                  "id": 501,
                  "order_id": 8812,
                  "order_reference": "TK-7H3KQ9",
                  "event_id": 12,
                  "date_id": 31,
                  "type_id": 44,
                  "type_name": "Adult",
                  "role": "ticket",
                  "seq": 1,
                  "status": "valid",
                  "holder_name": "John Smith",
                  "answers": {},
                  "seat": null,
                  "admits": 1,
                  "check_in": {
                    "people": 0,
                    "inside": 0,
                    "entries": 0,
                    "first_at": null,
                    "last_at": null,
                    "last_out_at": null,
                    "gate": ""
                  },
                  "currency": "AUD",
                  "price": 0,
                  "price_label": "A$0.00",
                  "face": 12.0,
                  "refunded": 0,
                  "refunded_at": null,
                  "block_reason": "",
                  "passed_on": false,
                  "replaces_id": 0,
                  "replaced_by_id": 0,
                  "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                },
                "order": {
                  "id": 8812,
                  "reference": "TK-7H3KQ9",
                  "status": "confirmed",
                  "buyer": {
                    "name": "John Smith",
                    "contact": "61412345678",
                    "email": ""
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/issued/{id}/void": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "voidTicket",
        "summary": "Void one ticket without a refund",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. The ticket stops working at the door and its place is back on sale. No money moves: to give money back use POST /tickets/orders/{id}/refund with `ticket_ids`. The buyer is told only with `notify` true. `ticket.order.refunded` is sent, with `money` none. 409 `ticket_not_allowed` when the ticket is already refunded, cancelled or passed on. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ticket's id (digits). The text of a ticket's QR code is never accepted in an address.",
            "type": "string",
            "x-example": "501"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "$ref": "#/definitions/TicketVoidRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Voided.",
            "schema": {
              "$ref": "#/definitions/TicketIssuedResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t5iv6",
                "ticket": {
                  "id": 502,
                  "order_id": 8812,
                  "order_reference": "TK-7H3KQ9",
                  "event_id": 12,
                  "date_id": 31,
                  "type_id": 44,
                  "type_name": "Adult",
                  "role": "ticket",
                  "seq": 2,
                  "status": "cancelled",
                  "holder_name": "John Smith",
                  "answers": {},
                  "seat": null,
                  "admits": 1,
                  "check_in": {
                    "people": 0,
                    "inside": 0,
                    "entries": 0,
                    "first_at": null,
                    "last_at": null,
                    "last_out_at": null,
                    "gate": ""
                  },
                  "currency": "AUD",
                  "price": 0,
                  "price_label": "A$0.00",
                  "face": 12.0,
                  "refunded": 0,
                  "refunded_at": null,
                  "block_reason": "",
                  "passed_on": false,
                  "replaces_id": 0,
                  "replaced_by_id": 0,
                  "page_url": "",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                },
                "order": {
                  "id": 8812,
                  "reference": "TK-7H3KQ9",
                  "status": "confirmed",
                  "kind": "comp",
                  "channel": "api",
                  "source": "",
                  "event": {
                    "id": 12,
                    "name": "Summer Quiz",
                    "slug": "summer-quiz"
                  },
                  "date": {
                    "id": 31,
                    "start": "2026-12-12T08:30:00.000Z",
                    "start_local": "2026-12-12T19:30",
                    "label": ""
                  },
                  "buyer": {
                    "name": "John Smith",
                    "contact": "61412345678",
                    "email": "",
                    "no_whatsapp": false
                  },
                  "currency": "AUD",
                  "total": 0,
                  "total_label": "A$0.00",
                  "tickets_total": 0,
                  "order_fee": 0,
                  "donation": 0,
                  "discount": 24.0,
                  "fees": 0,
                  "tax": 0,
                  "refunded": 0,
                  "refunded_label": "",
                  "ticket_count": 2,
                  "people_count": 2,
                  "addon_count": 0,
                  "promo_code": "",
                  "payment": {
                    "id": null,
                    "method": "",
                    "note": ""
                  },
                  "comp_reason": "guest",
                  "staff_note": "",
                  "created_by": "API key Zapier",
                  "attention": "",
                  "close_reason": "",
                  "refund_request": null,
                  "answers": {},
                  "marketing_optin": false,
                  "erased": false,
                  "page_url": "https://www.app2email.com/t/oq3k7m2xw5ya4n6bt2hc7r5dz3ef",
                  "expires": null,
                  "confirmed": "2026-11-06T01:00:00.000Z",
                  "cancelled": null,
                  "refunded_at": null,
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z",
                  "tickets": [
                    {
                      "id": 501,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 1,
                      "status": "valid",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 0,
                      "price_label": "A$0.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    },
                    {
                      "id": 502,
                      "order_id": 8812,
                      "order_reference": "TK-7H3KQ9",
                      "event_id": 12,
                      "date_id": 31,
                      "type_id": 44,
                      "type_name": "Adult",
                      "role": "ticket",
                      "seq": 2,
                      "status": "cancelled",
                      "holder_name": "John Smith",
                      "answers": {},
                      "seat": null,
                      "admits": 1,
                      "check_in": {
                        "people": 0,
                        "inside": 0,
                        "entries": 0,
                        "first_at": null,
                        "last_at": null,
                        "last_out_at": null,
                        "gate": ""
                      },
                      "currency": "AUD",
                      "price": 0,
                      "price_label": "A$0.00",
                      "face": 12.0,
                      "refunded": 0,
                      "refunded_at": null,
                      "block_reason": "",
                      "passed_on": false,
                      "replaces_id": 0,
                      "replaced_by_id": 0,
                      "page_url": "",
                      "created": "2026-11-06T01:00:00.000Z",
                      "updated": "2026-11-06T01:00:00.000Z"
                    }
                  ]
                },
                "note": "Voided. The ticket no longer works at the door and its place is back on sale. No money was moved."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/check-ins": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "checkInTicket",
        "summary": "Check a ticket in (or out) by its code or id",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. Send `code` (the text of the ticket's QR code; a link or other text around it is fine) with `date_id`, or `ticket_id`. The answer is always 200 when the request was understood: `result` ok and `admitted` true mean let the person in; any other `result` (already_in, not_inside, unknown, refunded, cancelled, transferred, blocked, wrong_event, wrong_date, wrong_gate, too_early, too_late) is a refusal with the reason in `note`, not an error. `direction` out checks out, for events that count people leaving; `people` admits a part of a group ticket; `force` admits although it is too early, too late or the wrong entrance. `check_in.id` is the handle for the undo. `ticket.checked_in` is sent the first time a ticket is admitted. The code of a whole order is not taken: 400 `invalid_ticket_check_in`. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketCheckInRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The result of the scan, admitted or refused.",
            "schema": {
              "$ref": "#/definitions/TicketCheckInResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t6ci7",
                "result": "ok",
                "admitted": true,
                "people": 1,
                "check_in": {
                  "id": 90211,
                  "at": "2026-11-06T01:00:00.000Z",
                  "direction": "in",
                  "gate": "g1",
                  "forced": false
                },
                "ticket": {
                  "id": 501,
                  "order_id": 8812,
                  "order_reference": "TK-7H3KQ9",
                  "event_id": 12,
                  "date_id": 31,
                  "type_id": 44,
                  "type_name": "Adult",
                  "role": "ticket",
                  "seq": 1,
                  "status": "valid",
                  "holder_name": "John Smith",
                  "answers": {},
                  "seat": null,
                  "admits": 1,
                  "check_in": {
                    "people": 1,
                    "inside": 1,
                    "entries": 1,
                    "first_at": "2026-11-06T01:00:00.000Z",
                    "last_at": "2026-11-06T01:00:00.000Z",
                    "last_out_at": null,
                    "gate": "g1"
                  },
                  "currency": "AUD",
                  "price": 0,
                  "price_label": "A$0.00",
                  "face": 12.0,
                  "refunded": 0,
                  "refunded_at": null,
                  "block_reason": "",
                  "passed_on": false,
                  "replaces_id": 0,
                  "replaced_by_id": 0,
                  "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                },
                "first": null,
                "note": "Checked in."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/check-ins/{scan_id}/undo": {
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "undoTicketCheckIn",
        "summary": "Take a check-in back",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. No body. Takes one accepted check-in back (`scan_id` is `check_in.id` of the check-in answer), so the ticket can be used again. Once per check-in, while its date has not ended. 404 `ticket_check_in_not_found`; 409 `ticket_not_allowed` when it was already taken back or the date has ended.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "scan_id",
            "in": "path",
            "required": true,
            "description": "The check-in's id: check_in.id of the answer of POST /tickets/check-ins.",
            "type": "string",
            "x-example": "90211"
          }
        ],
        "responses": {
          "200": {
            "description": "Taken back.",
            "schema": {
              "$ref": "#/definitions/TicketCheckInUndoResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t7cu8",
                "undone": true,
                "ticket": {
                  "id": 501,
                  "order_id": 8812,
                  "order_reference": "TK-7H3KQ9",
                  "event_id": 12,
                  "date_id": 31,
                  "type_id": 44,
                  "type_name": "Adult",
                  "role": "ticket",
                  "seq": 1,
                  "status": "valid",
                  "holder_name": "John Smith",
                  "answers": {},
                  "seat": null,
                  "admits": 1,
                  "check_in": {
                    "people": 0,
                    "inside": 0,
                    "entries": 0,
                    "first_at": null,
                    "last_at": null,
                    "last_out_at": null,
                    "gate": ""
                  },
                  "currency": "AUD",
                  "price": 0,
                  "price_label": "A$0.00",
                  "face": 12.0,
                  "refunded": 0,
                  "refunded_at": null,
                  "block_reason": "",
                  "passed_on": false,
                  "replaces_id": 0,
                  "replaced_by_id": 0,
                  "page_url": "https://www.app2email.com/t/kz5n2r7bq4hx3m6wy2ta5d7ce4gf",
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                },
                "note": "Taken back."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/codes": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTicketCodes",
        "summary": "The promo and access codes with their uses",
        "description": "Scope: `tickets:manage`. The promo codes (a discount) and the access codes (they unlock hidden ticket types), by id, each with how many orders and tickets used it. `q` searches in the code, `enabled` filters. Page with `next_cursor`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search in the code (2 to 80 characters).",
            "type": "string",
            "x-example": "EARLY"
          },
          {
            "name": "enabled",
            "in": "query",
            "required": false,
            "description": "true: only codes that are switched on. false: only the ones switched off.",
            "type": "boolean"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The codes.",
            "schema": {
              "$ref": "#/definitions/TicketCodesResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t8kl9",
                "codes": [
                  {
                    "id": 7,
                    "code": "EARLY10",
                    "kind": "percent",
                    "value": 10,
                    "currency": "",
                    "event_ids": [
                      12
                    ],
                    "type_ids": [],
                    "unlocks": [],
                    "starts": "",
                    "ends": "2026-12-01",
                    "limit": 100,
                    "limit_unit": "orders",
                    "enabled": true,
                    "batch": "",
                    "uses": {
                      "orders": 0,
                      "tickets": 0
                    },
                    "created": "2026-11-06T01:00:00.000Z",
                    "updated": "2026-11-06T01:00:00.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "createTicketCode",
        "summary": "Create a promo or access code",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. `code` is 3 to 20 characters of A-Z, 0-9, _ and - (stored in upper case). `kind` percent takes a whole `value` from 1 to 100, `kind` amount an amount in `currency` (the default is the number's). `event_ids` and `type_ids` limit where it counts ([] = everywhere), `unlocks` lists hidden ticket types the code opens (then `value` may be 0), `starts` and `ends` are days, `limit` caps the uses per `limit_unit`. 409 `ticket_not_allowed` when a code with this name exists; 409 `ticket_limit_reached` at 1,000 codes. Send an `Idempotency-Key` header to retry safely: the same key and body within 24 hours gets the first answer again (an error does not use the key up).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "type": "string",
            "maxLength": 255,
            "x-example": "order-1234-shipped"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketCodeRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created.",
            "schema": {
              "$ref": "#/definitions/TicketCodeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t9kc1",
                "code": {
                  "id": 7,
                  "code": "EARLY10",
                  "kind": "percent",
                  "value": 10,
                  "currency": "",
                  "event_ids": [
                    12
                  ],
                  "type_ids": [],
                  "unlocks": [],
                  "starts": "",
                  "ends": "2026-12-01",
                  "limit": 100,
                  "limit_unit": "orders",
                  "enabled": true,
                  "batch": "",
                  "uses": {
                    "orders": 0,
                    "tickets": 0
                  },
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/codes/{id}": {
      "patch": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "updateTicketCode",
        "summary": "Change a promo code or switch it off",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. By id or by the code itself. Send only the keys to change; the code's own text cannot be changed (make a new code instead). `enabled` false switches it off. 400 `nothing_to_change` without any key.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The promo code: its id, or the code itself.",
            "type": "string",
            "x-example": "EARLY10"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketCodeRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/TicketCodeResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t1ku2",
                "code": {
                  "id": 7,
                  "code": "EARLY10",
                  "kind": "percent",
                  "value": 10,
                  "currency": "",
                  "event_ids": [
                    12
                  ],
                  "type_ids": [],
                  "unlocks": [],
                  "starts": "",
                  "ends": "2026-12-01",
                  "limit": 100,
                  "limit_unit": "orders",
                  "enabled": false,
                  "batch": "",
                  "uses": {
                    "orders": 0,
                    "tickets": 0
                  },
                  "created": "2026-11-06T01:00:00.000Z",
                  "updated": "2026-11-06T01:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "deleteTicketCode",
        "summary": "Delete a promo code no order has used",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. By id or by the code itself. Only a code no order has used can be deleted: 409 `ticket_not_allowed` otherwise (switch it off with PATCH /tickets/codes/{id} instead).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The promo code: its id, or the code itself.",
            "type": "string",
            "x-example": "EARLY10"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/TicketCodeDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t2kd3",
                "deleted": 7
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/waitlist": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "listTicketWaitlist",
        "summary": "The waiting list of a sold-out date",
        "description": "Scope: `tickets:manage`. The people waiting for a place on one date, in the order they joined. `date_id` is needed (400 `invalid_ticket_event` without it). Left out, `status` gives the waiting and the notified entries. Page with `next_cursor`. `ticket.waitlist.joined` reports each new entry.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "date_id",
            "in": "query",
            "required": false,
            "description": "The date's id. Needed.",
            "type": "integer",
            "x-example": 31
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only entries in this state. Left out: waiting and notified.",
            "type": "string",
            "enum": [
              "waiting",
              "notified",
              "converted",
              "removed",
              "expired"
            ]
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many (1 to 200, default 50).",
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor of the previous answer, unchanged. Leave out for the first page.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The entries.",
            "schema": {
              "$ref": "#/definitions/TicketWaitlistResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t3wl4",
                "entries": [
                  {
                    "id": 77,
                    "event_id": 12,
                    "date_id": 31,
                    "type_id": 0,
                    "name": "Sample Contact",
                    "contact": "61412345678",
                    "email": "",
                    "quantity": 2,
                    "status": "waiting",
                    "notified": null,
                    "notify_count": 0,
                    "order_id": 0,
                    "created": "2026-11-06T01:00:00.000Z"
                  }
                ],
                "next_cursor": null,
                "count": 1
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/tickets/stats": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicketStats",
        "summary": "Sales and check-in figures of an event or one date",
        "description": "Scope: `tickets:manage`. The figures of one event, or of one of its dates with `date_id`: confirmed orders, people sold, held in baskets, left and checked in, the money (gross, discounts, fees, tax, donations, refunded, net) and the split by ticket type, by channel and by promo code. Money is in the event's currency. `event_id` is needed (400 `invalid_ticket_event` without it).",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "event_id",
            "in": "query",
            "required": false,
            "description": "The event: its id, its slug or its code (EV-XXXXX). Needed.",
            "type": "string",
            "x-example": "summer-quiz"
          },
          {
            "name": "date_id",
            "in": "query",
            "required": false,
            "description": "Only this date (its id). Left out: all dates of the event.",
            "type": "integer",
            "x-example": 31
          }
        ],
        "responses": {
          "200": {
            "description": "The figures.",
            "schema": {
              "$ref": "#/definitions/TicketStats"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t4st5",
                "event_id": 12,
                "date_id": null,
                "currency": "AUD",
                "orders": 41,
                "sold": 86,
                "held": 2,
                "left": 32,
                "capacity": 120,
                "checked_in": 0,
                "money": {
                  "gross": 1008.0,
                  "discounts": 0,
                  "fees": 0,
                  "tax": 0,
                  "donations": 0,
                  "refunded": 12.0,
                  "net": 996.0,
                  "net_label": "A$996.00"
                },
                "by_type": [
                  {
                    "type_id": 44,
                    "name": "Adult",
                    "role": "ticket",
                    "sold": 86,
                    "checked_in": 0,
                    "gross": 1008.0
                  }
                ],
                "by_channel": [
                  {
                    "channel": "web",
                    "orders": 40,
                    "tickets": 84,
                    "gross": 1008.0
                  },
                  {
                    "channel": "api",
                    "orders": 1,
                    "tickets": 2,
                    "gross": 0
                  }
                ],
                "by_code": []
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/settings/tickets": {
      "get": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "getTicketSettings",
        "summary": "The ticket settings and whether ticket sales are switched on",
        "description": "Scope: `tickets:manage`. Works for every number, also before ticket sales are set up. `available` says whether ticket sales are open for this number at all (false: every other ticket call answers 403 `tickets_not_enabled`), `configured` whether the number has ticket settings, `enabled` and `selling` whether tickets are sold now, and `why` not (tables_missing, no_config, removed, off, plan). Also the address of the events page, the currency and the time zone new events start with, which of the business's payment providers can take a ticket payment, and `config`: the settings with every default filled in. Nothing is changed by this call.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The settings.",
            "schema": {
              "$ref": "#/definitions/TicketSettings"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t8sg1",
                "available": true,
                "configured": true,
                "enabled": true,
                "selling": true,
                "why": "",
                "events_url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7",
                "currency": "AUD",
                "timezone": "Australia/Sydney",
                "payments": {
                  "stripe": true,
                  "paypal": false
                },
                "config": {
                  "organiser": {
                    "name": "",
                    "email": "",
                    "phone": ""
                  },
                  "hold_minutes": 10,
                  "notify": {
                    "sale": "each",
                    "email": ""
                  },
                  "brand": {
                    "logo": 0,
                    "color": "",
                    "background": "",
                    "hide_powered": false
                  },
                  "ticket_style": {
                    "layout": "classic",
                    "accent": "",
                    "background": "#FFFFFF",
                    "text": "#111111",
                    "image": 0,
                    "image_as": "cover",
                    "logo": 0,
                    "font": "inter",
                    "fields": {
                      "holder": true,
                      "seat": true,
                      "type": true,
                      "reference": true,
                      "venue": true,
                      "doors": true,
                      "price": false,
                      "terms": false
                    },
                    "footer": ""
                  },
                  "wa": {
                    "keywords": [
                      "tickets",
                      "ticket",
                      "events"
                    ],
                    "intro_text": "Tap the button to see what's on and get your tickets.",
                    "cta": "Get tickets",
                    "mine_keywords": [
                      "my tickets",
                      "my ticket"
                    ],
                    "send_pdf": false,
                    "texts": {
                      "none_text": "There are no events on sale right now.",
                      "pay_text": "Order {reference}\n{lines}\nTotal: {total}\n\nWe are holding your tickets for {time}. Tap Pay now to finish."
                    }
                  },
                  "privacy": {
                    "retention_days": 0,
                    "url": ""
                  },
                  "texts": {
                    "refund_none": "No refunds unless the event is cancelled or its date or venue changes.",
                    "hold_ended": "Your tickets were released because the time ran out. Please choose again."
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "put": {
        "tags": [
          "Tickets-and-Pay"
        ],
        "operationId": "updateTicketSettings",
        "summary": "Switch ticket sales on or off and change the settings",
        "description": "Scope: `tickets:manage`. Not with a sandbox key. `enabled` switches ticket sales on or off; `config` holds whole sections of the settings (organiser, hold_minutes, notify, brand, ticket_style, wa, privacy, texts): a section sent replaces the stored section, the others stay. The first call makes the ticket settings of the number. Switching off never strands what was sold: the tickets, refunds and the door go on working. 403 `tickets_not_enabled` while ticket sales are not open for this number, 403 `plan_not_allowed`, 400 `invalid_setting` with `details.problems`, 400 `nothing_to_change` with neither key. The answer is the one of GET /settings/tickets plus `note`.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TicketSettingsRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "schema": {
              "$ref": "#/definitions/TicketSettings"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "t9sp2",
                "available": true,
                "configured": true,
                "enabled": true,
                "selling": true,
                "why": "",
                "events_url": "https://www.app2email.com/events/k3XbQ9rTzP2mWv7",
                "currency": "AUD",
                "timezone": "Australia/Sydney",
                "payments": {
                  "stripe": true,
                  "paypal": false
                },
                "config": {
                  "organiser": {
                    "name": "",
                    "email": "",
                    "phone": ""
                  },
                  "hold_minutes": 10,
                  "notify": {
                    "sale": "each",
                    "email": ""
                  },
                  "brand": {
                    "logo": 0,
                    "color": "",
                    "background": "",
                    "hide_powered": false
                  },
                  "ticket_style": {
                    "layout": "classic",
                    "accent": "",
                    "background": "#FFFFFF",
                    "text": "#111111",
                    "image": 0,
                    "image_as": "cover",
                    "logo": 0,
                    "font": "inter",
                    "fields": {
                      "holder": true,
                      "seat": true,
                      "type": true,
                      "reference": true,
                      "venue": true,
                      "doors": true,
                      "price": false,
                      "terms": false
                    },
                    "footer": ""
                  },
                  "wa": {
                    "keywords": [
                      "tickets",
                      "ticket",
                      "events"
                    ],
                    "intro_text": "Tap the button to see what's on and get your tickets.",
                    "cta": "Get tickets",
                    "mine_keywords": [
                      "my tickets",
                      "my ticket"
                    ],
                    "send_pdf": false,
                    "texts": {
                      "none_text": "There are no events on sale right now.",
                      "pay_text": "Order {reference}\n{lines}\nTotal: {total}\n\nWe are holding your tickets for {time}. Tap Pay now to finish."
                    }
                  },
                  "privacy": {
                    "retention_days": 0,
                    "url": ""
                  },
                  "texts": {
                    "refund_none": "No refunds unless the event is cancelled or its date or venue changes.",
                    "hold_ended": "Your tickets were released because the time ran out. Please choose again."
                  }
                },
                "note": "Saved."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/test-url": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "testWebhookUrl",
        "summary": "Send a test event to any URL",
        "description": "One signed POST to any https URL, answered with the exact request sent and your URL's answer. No saved webhook needed. Shares the 30 tests an hour of the number (429 too_many_tests with Retry-After); 60 an hour per target host and per its IP address.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/WebhookTestUrlRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The test was made: see result.ok and result.stage.",
            "schema": {
              "$ref": "#/definitions/WebhookTestUrlResponse"
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/catchers": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhookCatcher",
        "summary": "Get a temporary URL that keeps what it receives",
        "description": "A URL for 1 hour that keeps up to 50 requests of up to 64 KB: use it as a webhook URL or in test-url, then read them. POST https://api.app2email.com/hooks/catch/{token} needs no key and answers 200 {\"ok\":true}; 404 unknown, 410 expired, 413 over 64 KB, 429 full. At most 3 per number at a time.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "201": {
            "description": "Made.",
            "schema": {
              "$ref": "#/definitions/WebhookCatcherCreated"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4tch",
                "token": "Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C",
                "url": "https://api.app2email.com/hooks/catch/Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C",
                "created": "2026-11-06T01:00:00.000Z",
                "expires": "2026-11-06T02:00:00.000Z",
                "limits": {
                  "requests": 50,
                  "body_max_bytes": 65536,
                  "minutes": 60
                },
                "note": "Use the url as a webhook (POST .../webhooks {\"url\": ...}) or in test-url, then read what came: GET .../webhooks/catchers/Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C?after=<last seq>."
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookCatchers",
        "summary": "Your catchers",
        "description": "The number's catchers that have not expired.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          }
        ],
        "responses": {
          "200": {
            "description": "The catchers.",
            "schema": {
              "$ref": "#/definitions/WebhookCatchersResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4tcl",
                "catchers": [
                  {
                    "token": "Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C",
                    "url": "https://api.app2email.com/hooks/catch/Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C",
                    "created": "2026-11-06T01:00:00.000Z",
                    "expires": "2026-11-06T02:00:00.000Z",
                    "requests": 2,
                    "full": false
                  }
                ],
                "limits": {
                  "catchers": 3,
                  "requests": 50,
                  "body_max_bytes": 65536
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    },
    "/v1/{number}/webhooks/catchers/{token}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookCatcher",
        "summary": "What a catcher received",
        "description": "The requests, oldest first, with their headers and body. Poll with after = the last seq you have.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The catcher's token.",
            "type": "string",
            "x-example": "Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C"
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "Only the requests after this seq.",
            "type": "integer",
            "minimum": 0,
            "x-example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "The catcher and its requests.",
            "schema": {
              "$ref": "#/definitions/WebhookCatcherResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4tcg",
                "token": "Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C",
                "url": "https://api.app2email.com/hooks/catch/Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C",
                "created": "2026-11-06T01:00:00.000Z",
                "expires": "2026-11-06T02:00:00.000Z",
                "full": false,
                "count": 1,
                "requests": [
                  {
                    "seq": 1,
                    "received": "2026-11-06T01:00:03.120Z",
                    "method": "POST",
                    "headers": {
                      "Content-Type": "application/json; charset=utf-8",
                      "User-Agent": "app2email-webhooks/1.0",
                      "X-App2email-Event": "message.status",
                      "X-App2email-Delivery": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                      "X-App2email-Signature": "t=1762390800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",
                      "X-Hub-Signature-256": "sha256=7d0e8a4a2a5c0b8b1a8f3f62c1d0e2b5c6f8a9e0d1c2b3a4f5e6d7c8b9a0f1e2"
                    },
                    "body": "{\"id\":\"evt_Xq3k9m2Lw8Rt5Yp1Zs01\",\"type\":\"message.status\",\"created\":\"2026-11-06T01:00:03.100Z\",\"number\":\"4976659348270\",\"data\":{\"message_id\":\"wamid.SANDBOX.k3XbQ9rTzP2mWv7a1c9eQ7cT\",\"to\":\"61412345678\",\"status\":\"delivered\",\"timestamp\":\"2026-11-06T01:00:03.000Z\",\"sent_by\":\"api\"}}",
                    "body_truncated": false
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhookCatcher",
        "summary": "Delete a catcher",
        "description": "Deletes it and what it received. Its URL answers 404 from then on.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "x-example": "4976659348270",
            "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only."
          },
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The catcher's token.",
            "type": "string",
            "x-example": "Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "schema": {
              "$ref": "#/definitions/WebhookCatcherDeleteResponse"
            },
            "examples": {
              "application/json": {
                "success": true,
                "request_id": "c4tcd",
                "deleted": "Q7cT2mX9pLk3vB8nR1sWd4Fh6Jk0Zx2C"
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "SendTemplateRequest": {
      "type": "object",
      "description": "A WhatsApp message in the format of WhatsApp Cloud API (Meta's exact body works unchanged): a template (type 'template', the default, any time), or within 24 hours of the contact's last message a free-form text, image, video, document, audio, sticker, location, contacts, reaction or interactive message. Meta's mark-read body {messaging_product, status: 'read', message_id, typing_indicator?} marks a message as read. Give 'to' or 'recipients' (templates only).",
      "properties": {
        "messaging_product": {
          "type": "string",
          "enum": [
            "whatsapp"
          ],
          "description": "Optional. Always 'whatsapp'."
        },
        "recipient_type": {
          "type": "string",
          "enum": [
            "individual"
          ],
          "description": "Optional. Always 'individual'."
        },
        "to": {
          "type": "string",
          "example": "61412345678",
          "description": "Recipient's WhatsApp number with country code. Digits only is best (spaces, '+', '-' are removed). Several recipients: separate the numbers with commas, eg \"61412345678,61498765432\" (semicolons and new lines work too), or send a JSON array of numbers. Each number gets its own message, and the response lists the result per number in 'results'. A free-form message (not 'template') goes to one number. A business-scoped user id (eg 61.AbC123, from from_user_id) is accepted as it is."
        },
        "recipient": {
          "type": "string",
          "example": "61.AbC123xyz",
          "description": "Optional, instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'."
        },
        "segment": {
          "type": "string",
          "example": "VIP, consented",
          "description": "Optional, app2email only, instead of 'to' / 'recipients': the id or name of a saved segment (GET /segments). Templates only. Each contact's named template parameters without a value are filled from its custom_fields ('name' from the contact's name). Recorded as a broadcast."
        },
        "type": {
          "type": "string",
          "enum": [
            "template",
            "text",
            "image",
            "video",
            "document",
            "interactive",
            "audio",
            "sticker",
            "location",
            "contacts",
            "reaction"
          ],
          "default": "template",
          "description": "'template' (default): an approved template. Otherwise a free-form message within the 24 hour window; the field of the same name holds it. Left out with status 'read': mark as read."
        },
        "interactive": {
          "$ref": "#/definitions/Interactive",
          "description": "type 'interactive': reply buttons, a list, or a URL button."
        },
        "template": {
          "$ref": "#/definitions/Template"
        },
        "text": {
          "$ref": "#/definitions/FreeFormText",
          "description": "type 'text': the message."
        },
        "image": {
          "$ref": "#/definitions/FreeFormMedia",
          "description": "type 'image': link, data+filename or id, and an optional caption."
        },
        "video": {
          "$ref": "#/definitions/FreeFormMedia",
          "description": "type 'video': link, data+filename or id, and an optional caption."
        },
        "document": {
          "$ref": "#/definitions/FreeFormMedia",
          "description": "type 'document': link, data+filename or id, and an optional caption."
        },
        "reply_to": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
          "description": "Optional, free-form only: the message_id of one of the contact's messages, quoted by this one. Meta's 'context': {\"message_id\": ...} works too."
        },
        "send_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-11-02T09:00:00+11:00",
          "description": "Optional, templates only: send later. ISO 8601 with a time zone ('Z' or '+11:00'), 1 minute to 29 days ahead. The answer is HTTP 202 with status 'scheduled'."
        },
        "campaign_name": {
          "type": "string",
          "maxLength": 100,
          "example": "October newsletter",
          "description": "Optional, app2email only. Several numbers in 'to' (or 'recipients'): the name of the broadcast this list is recorded as (Activity Log under Broadcasts). Default \"API: <template name>\". Not used for one number."
        },
        "recipients": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Recipient"
          },
          "description": "Optional, app2email only, instead of 'to': each number with its own values. Each entry's components replace the shared template.components of the same type (a button: the same index). Every number is checked before anything is sent."
        },
        "dry_run": {
          "type": "boolean",
          "default": false,
          "description": "Optional, app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything."
        },
        "background": {
          "type": "boolean",
          "default": false,
          "description": "Optional, app2email only. true: answer HTTP 202 once everything is checked and the media uploaded, then send. Progress: broadcast.status_url (GET /v1/{number}/broadcasts/{code}) or the broadcast.completed webhook event."
        },
        "audio": {
          "$ref": "#/definitions/AudioContent",
          "description": "type 'audio'."
        },
        "sticker": {
          "$ref": "#/definitions/StickerContent",
          "description": "type 'sticker'."
        },
        "location": {
          "$ref": "#/definitions/LocationContent",
          "description": "type 'location'."
        },
        "contacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ContactCard"
          },
          "description": "type 'contacts': 1 to 20 cards."
        },
        "reaction": {
          "$ref": "#/definitions/ReactionContent",
          "description": "type 'reaction'."
        },
        "context": {
          "type": "object",
          "properties": {
            "message_id": {
              "type": "string"
            }
          },
          "description": "Meta's form of reply_to."
        },
        "callback_data": {
          "type": "string",
          "maxLength": 512,
          "example": "order-1234",
          "description": "Optional. Sent to WhatsApp as biz_opaque_callback_data; back as data.callback_data in this message's message.status events. Meta's own field name works too."
        },
        "recipient_identity_key_hash": {
          "type": "string",
          "maxLength": 200,
          "example": "DF2lS5v2W6x=",
          "description": "Optional, one recipient (per number: in recipients[]): delivered only while the contact's identity key has this hash (message.received data.identity_key_hash); else message.failed, 137000 recipient_identity_changed. Needs PUT /settings/identity-check."
        },
        "marketing_api": {
          "type": "string",
          "enum": [
            "auto",
            "cloud_api",
            "mm_api"
          ],
          "description": "Optional, MARKETING templates: the path for this send (true = mm_api, false = cloud_api). Default: the number's setting messages.marketing_route (auto)."
        },
        "product_policy": {
          "type": "string",
          "enum": [
            "CLOUD_API_FALLBACK",
            "STRICT"
          ],
          "description": "Optional, Marketing Messages API only: STRICT = no fallback to the Cloud API. Default CLOUD_API_FALLBACK."
        },
        "message_activity_sharing": {
          "type": "boolean",
          "description": "Optional, Marketing Messages API only: share read and click activity with Meta for this message."
        },
        "status": {
          "type": "string",
          "enum": [
            "read"
          ],
          "description": "Meta's mark-read body: 'read' with message_id (no type)."
        },
        "message_id": {
          "type": "string",
          "description": "Meta's mark-read body: the received message."
        },
        "typing_indicator": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "text"
              ]
            }
          },
          "description": "Meta's mark-read body: also show the typing indicator."
        }
      },
      "example": {
        "to": "61412345678",
        "type": "template",
        "template": {
          "name": "order_update",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "John"
                },
                {
                  "type": "text",
                  "text": "#1234"
                }
              ]
            }
          ]
        }
      }
    },
    "Recipient": {
      "type": "object",
      "required": [
        "to"
      ],
      "properties": {
        "to": {
          "type": "string",
          "example": "61412345678",
          "description": "One number, with country code."
        },
        "components": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Component"
          },
          "description": "Only what differs for this number, eg its body values. The rest comes from template.components."
        },
        "recipient_identity_key_hash": {
          "type": "string",
          "maxLength": 200,
          "description": "Optional: this contact's identity_key_hash (see the request's)."
        }
      }
    },
    "Template": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "example": "order_update",
          "description": "Exact name of an APPROVED template."
        },
        "language": {
          "$ref": "#/definitions/Language"
        },
        "components": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Component"
          },
          "description": "Values for the template's placeholders and media. Leave out for templates without parameters."
        }
      }
    },
    "Language": {
      "type": "object",
      "required": [
        "code"
      ],
      "description": "Required when the template exists in more than one language.",
      "properties": {
        "code": {
          "type": "string",
          "example": "en",
          "description": "Template language code, eg 'en', 'en_US', 'nl'."
        }
      }
    },
    "Component": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "header",
            "body",
            "button",
            "carousel",
            "limited_time_offer"
          ]
        },
        "sub_type": {
          "type": "string",
          "enum": [
            "url",
            "quick_reply",
            "copy_code",
            "flow",
            "catalog",
            "mpm",
            "spm",
            "order_details"
          ],
          "description": "Buttons only."
        },
        "index": {
          "type": "string",
          "example": "0",
          "description": "Buttons only: position of the button in the template, starting at 0."
        },
        "parameters": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Parameter"
          }
        },
        "cards": {
          "type": "array",
          "description": "type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.",
          "items": {
            "type": "object",
            "properties": {
              "card_index": {
                "type": "integer"
              },
              "components": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/Component"
                }
              }
            }
          }
        }
      }
    },
    "Parameter": {
      "type": "object",
      "required": [
        "type"
      ],
      "description": "One value. Set 'type' and the matching field, eg {\"type\":\"text\",\"text\":\"John\"} or {\"type\":\"image\",\"image\":{\"link\":\"https://...\"}}.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "text",
            "image",
            "video",
            "document",
            "location",
            "currency",
            "date_time",
            "payload",
            "coupon_code",
            "action",
            "product",
            "limited_time_offer"
          ]
        },
        "parameter_name": {
          "type": "string",
          "description": "For templates with NAMED placeholders, eg 'first_name' for {{first_name}}."
        },
        "text": {
          "type": "string",
          "description": "type 'text'. No new lines, tabs or more than 4 spaces in a row."
        },
        "image": {
          "$ref": "#/definitions/Media"
        },
        "video": {
          "$ref": "#/definitions/Media"
        },
        "document": {
          "$ref": "#/definitions/Media"
        },
        "location": {
          "$ref": "#/definitions/Location"
        },
        "currency": {
          "$ref": "#/definitions/Currency"
        },
        "date_time": {
          "$ref": "#/definitions/DateTime"
        },
        "payload": {
          "type": "string",
          "description": "type 'payload': quick reply button payload."
        },
        "coupon_code": {
          "type": "string",
          "description": "type 'coupon_code': copy code button value."
        },
        "action": {
          "type": "object",
          "additionalProperties": true,
          "description": "type 'action': flow / catalog button data, as WhatsApp Cloud API."
        },
        "product": {
          "type": "object",
          "properties": {
            "product_retailer_id": {
              "type": "string"
            },
            "catalog_id": {
              "type": "string"
            }
          },
          "description": "type 'product': a product header."
        },
        "limited_time_offer": {
          "type": "object",
          "properties": {
            "expiration_time_ms": {
              "type": "integer",
              "example": 1767225600000
            }
          },
          "description": "type 'limited_time_offer': when the offer ends (ms since 1970)."
        }
      }
    },
    "Media": {
      "type": "object",
      "description": "Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.",
      "properties": {
        "link": {
          "type": "string",
          "format": "uri",
          "example": "https://example.com/photo.jpg",
          "description": "Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp."
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
        },
        "id": {
          "type": "string",
          "description": "A media id already uploaded to WhatsApp for this number."
        },
        "filename": {
          "type": "string",
          "example": "invoice.pdf",
          "description": "Shown to the recipient for documents. Also helps detect the file type."
        },
        "mime_type": {
          "type": "string",
          "example": "application/pdf",
          "description": "Optional. The type is detected from the file where possible."
        }
      }
    },
    "Location": {
      "type": "object",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "string",
          "example": "-33.8688"
        },
        "longitude": {
          "type": "string",
          "example": "151.2093"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      }
    },
    "Currency": {
      "type": "object",
      "properties": {
        "fallback_value": {
          "type": "string",
          "example": "$10.50"
        },
        "code": {
          "type": "string",
          "example": "USD"
        },
        "amount_1000": {
          "type": "integer",
          "example": 10500
        }
      }
    },
    "DateTime": {
      "type": "object",
      "properties": {
        "fallback_value": {
          "type": "string",
          "example": "February 25, 2026"
        }
      }
    },
    "SendMessageResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "kxrkf"
        },
        "message_id": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
          "description": "WhatsApp message id."
        },
        "status": {
          "type": "string",
          "enum": [
            "accepted",
            "partially_accepted",
            "failed",
            "queued",
            "scheduled",
            "dry_run",
            "pending_approval"
          ],
          "description": "accepted: accepted by WhatsApp (delivered/read status: GET /messages/{message_id} or the message.status webhook). partially_accepted / failed: a list where some / none were accepted. queued: background send started (HTTP 202). scheduled: 'send_at' given, sending later (HTTP 202; scheduled_for and the broadcast code). dry_run: a test, nothing sent. pending_approval: held by the key's approval gate (HTTP 202; 'approval' has the id and url)."
        },
        "sandbox": {
          "type": "boolean",
          "description": "true: a sandbox key simulated the send; nothing went to WhatsApp (message ids start with wamid.SANDBOX.)."
        },
        "approval": {
          "type": "object",
          "description": "status pending_approval only.",
          "properties": {
            "id": {
              "type": "string",
              "example": "apr_a1b2c3d4e5f6g7h8"
            },
            "url": {
              "type": "string",
              "description": "The dashboard page to approve or reject it."
            },
            "expires": {
              "type": "string",
              "format": "date-time"
            },
            "recipients": {
              "type": "integer"
            },
            "key": {
              "type": "string"
            }
          }
        },
        "summary": {
          "type": "object",
          "additionalProperties": true,
          "description": "status pending_approval only: what was held (recipients, template, text)."
        },
        "type": {
          "type": "string",
          "enum": [
            "template",
            "text",
            "image",
            "video",
            "document",
            "interactive",
            "audio",
            "sticker",
            "location",
            "contacts",
            "reaction"
          ],
          "description": "Free-form replies: the message type. Templates: 'template'."
        },
        "from": {
          "type": "string",
          "example": "4976659348270"
        },
        "to": {
          "type": "string",
          "example": "61412345678"
        },
        "window_closes_at": {
          "type": "string",
          "format": "date-time",
          "description": "Free-form replies: when the 24 hour window closes (after the contact's last message)."
        },
        "scheduled_for": {
          "type": "string",
          "format": "date-time",
          "description": "send_at only: when the send starts (UTC)."
        },
        "scheduled": {
          "type": "integer",
          "description": "send_at only: how many messages are scheduled."
        },
        "template": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "category": {
              "type": "string"
            }
          }
        },
        "text": {
          "type": "string",
          "description": "The message text with your values filled in."
        },
        "media": {
          "type": "string",
          "description": "The header media sent, if any."
        },
        "conversation_url": {
          "type": "string",
          "description": "Conversation history page on app2email.com."
        },
        "note": {
          "type": "string"
        },
        "broadcast": {
          "type": "object",
          "description": "Several numbers in 'to' only: the broadcast this list is recorded as.",
          "properties": {
            "name": {
              "type": "string",
              "example": "October newsletter"
            },
            "code": {
              "type": "string"
            },
            "report_url": {
              "type": "string",
              "description": "The broadcast's report page on app2email.com, with delivered/read counts per number."
            },
            "status_url": {
              "type": "string",
              "description": "GET it (with your API key) for the broadcast's status and the result per number."
            }
          }
        },
        "recipients": {
          "type": "integer",
          "description": "Several numbers in 'to' only: how many different numbers were given."
        },
        "accepted": {
          "type": "integer",
          "description": "Several numbers only: how many messages WhatsApp accepted."
        },
        "failed": {
          "type": "integer",
          "description": "Several numbers only: how many were not sent (see results)."
        },
        "results": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RecipientResult"
          },
          "description": "Several numbers only: one entry per number, in the order given."
        },
        "error": {
          "$ref": "#/definitions/Error",
          "description": "Several numbers only, when none were sent: the first number's error."
        },
        "queued": {
          "type": "integer",
          "description": "Background send (HTTP 202): how many messages will be sent."
        },
        "skipped": {
          "type": "integer",
          "description": "Background send: how many numbers are skipped (listed in results, eg Do Not Call list)."
        },
        "dry_run": {
          "type": "boolean",
          "description": "Dry run only: true."
        },
        "would_send": {
          "type": "integer",
          "description": "Dry run only: how many messages would be sent."
        },
        "would_skip": {
          "type": "integer",
          "description": "Dry run only: how many numbers would be skipped (see results)."
        },
        "messages_left_this_month": {
          "type": "integer",
          "description": "Dry run only: messages left this billing month (the plan limit covers outgoing WhatsApp + outgoing emails)."
        },
        "broadcast_name": {
          "type": "string",
          "description": "Dry run of a list: the name the broadcast would get."
        },
        "whatsapp_status": {
          "type": "string",
          "enum": [
            "accepted",
            "held_for_quality_assessment",
            "paused"
          ],
          "description": "WhatsApp's own message_status for paced templates: held_for_quality_assessment = WhatsApp holds it while it checks the template's quality (it may be dropped later, 132015). Not app2email's approval gate."
        },
        "contacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SendContact"
          },
          "description": "WhatsApp's contacts[]: the wa_id and business-scoped user_id it resolved."
        },
        "sent_via": {
          "type": "string",
          "enum": [
            "cloud_api",
            "mm_api"
          ],
          "description": "MARKETING templates: the path used (cloud_api = /messages, mm_api = the Marketing Messages API). Dry run: the path it would take."
        },
        "whatsapp_edge": {
          "type": "string",
          "enum": [
            "messages",
            "marketing_messages"
          ],
          "description": "Dry run of a template: the WhatsApp endpoint the message would go to."
        }
      }
    },
    "RecipientResult": {
      "type": "object",
      "properties": {
        "to": {
          "type": "string",
          "example": "61412345678"
        },
        "success": {
          "type": "boolean"
        },
        "message_id": {
          "type": "string",
          "description": "WhatsApp message id, when accepted."
        },
        "status": {
          "type": "string",
          "enum": [
            "accepted"
          ]
        },
        "text": {
          "type": "string",
          "description": "This number's message text, when the numbers had different values ('recipients')."
        },
        "conversation_url": {
          "type": "string"
        },
        "error": {
          "$ref": "#/definitions/Error",
          "description": "Why this number was not sent, eg recipient_opted_out, monthly_limit_reached, recipient_unreachable."
        },
        "would_send": {
          "type": "boolean",
          "description": "Dry run only."
        },
        "whatsapp_message": {
          "type": "object",
          "additionalProperties": true,
          "description": "Dry run only: the exact message WhatsApp would get."
        },
        "whatsapp_status": {
          "type": "string"
        },
        "contacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SendContact"
          }
        },
        "sent_via": {
          "type": "string",
          "enum": [
            "cloud_api",
            "mm_api"
          ]
        }
      }
    },
    "MessageTimes": {
      "type": "object",
      "description": "When each step happened (ISO 8601, UTC). Steps not reached are left out.",
      "properties": {
        "submitted": {
          "type": "string",
          "format": "date-time"
        },
        "accepted": {
          "type": "string",
          "format": "date-time"
        },
        "sent": {
          "type": "string",
          "format": "date-time"
        },
        "delivered": {
          "type": "string",
          "format": "date-time"
        },
        "read": {
          "type": "string",
          "format": "date-time"
        },
        "failed": {
          "type": "string",
          "format": "date-time"
        },
        "deleted": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "MessageInfo": {
      "type": "object",
      "properties": {
        "message_id": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA="
        },
        "to": {
          "type": "string",
          "example": "61412345678"
        },
        "status": {
          "type": "string",
          "enum": [
            "accepted",
            "sent",
            "delivered",
            "read",
            "failed",
            "deleted",
            "queued",
            "unknown"
          ]
        },
        "error": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            }
          },
          "description": "Why it failed."
        },
        "sent_by": {
          "type": "string",
          "enum": [
            "api",
            "broadcast",
            "email_reply",
            "app2email"
          ]
        },
        "broadcast_code": {
          "type": "string",
          "description": "When the message was part of a broadcast."
        },
        "text": {
          "type": "string"
        },
        "media": {
          "type": "string"
        },
        "times": {
          "$ref": "#/definitions/MessageTimes"
        },
        "reply": {
          "type": "object",
          "description": "The contact's reply to this message.",
          "properties": {
            "at": {
              "type": "string",
              "format": "date-time"
            },
            "button": {
              "type": "string"
            },
            "text": {
              "type": "string"
            }
          }
        },
        "conversation_url": {
          "type": "string"
        }
      }
    },
    "MessageStatusResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "message_id": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA="
        },
        "to": {
          "type": "string",
          "example": "61412345678"
        },
        "status": {
          "type": "string",
          "enum": [
            "accepted",
            "sent",
            "delivered",
            "read",
            "failed",
            "deleted",
            "queued",
            "unknown"
          ]
        },
        "error": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            }
          },
          "description": "Why it failed."
        },
        "sent_by": {
          "type": "string",
          "enum": [
            "api",
            "broadcast",
            "email_reply",
            "app2email"
          ]
        },
        "broadcast_code": {
          "type": "string",
          "description": "When the message was part of a broadcast."
        },
        "text": {
          "type": "string"
        },
        "media": {
          "type": "string"
        },
        "times": {
          "$ref": "#/definitions/MessageTimes"
        },
        "reply": {
          "type": "object",
          "description": "The contact's reply to this message.",
          "properties": {
            "at": {
              "type": "string",
              "format": "date-time"
            },
            "button": {
              "type": "string"
            },
            "text": {
              "type": "string"
            }
          }
        },
        "conversation_url": {
          "type": "string"
        }
      }
    },
    "BroadcastSummary": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "example": "k3XbQ9rTzP2mWv7a1c9e"
        },
        "name": {
          "type": "string"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "inprogress",
            "completed",
            "cancelled",
            "missed",
            "interrupted",
            "pending",
            "unknown"
          ],
          "description": "scheduled: waiting for send_at. missed: the scheduled time passed while the service was down (not sent). interrupted: cut off by a restart."
        },
        "scheduled_for": {
          "type": "string",
          "format": "date-time",
          "description": "Only when status is scheduled."
        },
        "sent_by": {
          "type": "string",
          "enum": [
            "api",
            "dashboard"
          ]
        },
        "template": {
          "type": "string"
        },
        "numbers": {
          "type": "integer"
        },
        "status_url": {
          "type": "string"
        },
        "report_url": {
          "type": "string"
        }
      }
    },
    "BroadcastsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "broadcasts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BroadcastSummary"
          }
        }
      }
    },
    "BroadcastStatusResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "broadcast": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "created": {
              "type": "string",
              "format": "date-time"
            },
            "status": {
              "type": "string",
              "enum": [
                "scheduled",
                "inprogress",
                "completed",
                "cancelled",
                "missed",
                "interrupted",
                "pending",
                "unknown"
              ]
            },
            "status_notes": {
              "type": "string"
            },
            "scheduled_for": {
              "type": "string",
              "format": "date-time"
            },
            "sent_by": {
              "type": "string",
              "enum": [
                "api",
                "dashboard"
              ]
            },
            "template": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "language": {
                  "type": "string"
                }
              }
            },
            "report_url": {
              "type": "string"
            }
          }
        },
        "counts": {
          "type": "object",
          "description": "Live from the messages: numbers, skipped_do_not_call, skipped_monthly_limit, posted, accepted, sent, delivered, read, failed, replied, opted_out.",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "results": {
          "type": "array",
          "description": "One per number: a MessageInfo, or {to, status: skipped|not_sent|pending, reason}.",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "UsageResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "plan": {
          "type": "string",
          "example": "standard_5000"
        },
        "service_status": {
          "type": "string",
          "example": "LIVE"
        },
        "billing_period": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string",
              "format": "date-time"
            },
            "end": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "whatsapp_messages": {
          "type": "object",
          "description": "used: WhatsApp messages sent. limit and left: the plan's, shared with outgoing email - see plan_messages.",
          "properties": {
            "used": {
              "type": "integer"
            },
            "limit": {
              "type": "integer"
            },
            "left": {
              "type": "integer"
            }
          }
        },
        "plan_messages": {
          "type": "object",
          "description": "The plan limit covers outgoing WhatsApp + outgoing emails added together.",
          "properties": {
            "whatsapp_sent": {
              "type": "integer"
            },
            "emails_sent": {
              "type": "integer"
            },
            "total_sent": {
              "type": "integer"
            },
            "limit": {
              "type": "integer"
            },
            "left": {
              "type": "integer"
            }
          }
        },
        "messages_received_this_billing_month": {
          "type": "integer"
        },
        "max_numbers_per_request": {
          "type": "integer"
        },
        "broadcasts_this_billing_month": {
          "type": "integer"
        },
        "do_not_call_list": {
          "type": "object",
          "properties": {
            "count": {
              "type": "integer"
            }
          }
        },
        "webhooks": {
          "type": "integer"
        },
        "monthly_cap": {
          "type": "integer",
          "description": "The number's own monthly cap (settings caps.monthly_messages). Left out when there is none."
        },
        "meta_pricing": {
          "$ref": "#/definitions/MetaPricing"
        }
      }
    },
    "DoNotCallEntry": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string",
          "example": "61412345678"
        },
        "name": {
          "type": "string"
        },
        "added": {
          "type": "string",
          "format": "date-time"
        },
        "source": {
          "type": "string",
          "enum": [
            "stop_promotions",
            "whatsapp_stop",
            "manual",
            "upload",
            "api"
          ]
        },
        "note": {
          "type": "string"
        }
      }
    },
    "DoNotCallListResponse": {
      "type": "object",
      "description": "The whole list, or with ?number= whether that number is on it.",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "count": {
          "type": "integer"
        },
        "numbers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/DoNotCallEntry"
          }
        },
        "number": {
          "type": "string",
          "description": "?number= only."
        },
        "on_list": {
          "type": "boolean",
          "description": "?number= only."
        },
        "entry": {
          "$ref": "#/definitions/DoNotCallEntry"
        }
      }
    },
    "DoNotCallAddRequest": {
      "type": "object",
      "description": "Up to 1000 numbers: strings, or objects with a name and note. Or one entry: {\"number\": ..., \"name\": ..., \"note\": ...}.",
      "properties": {
        "numbers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "example": [
            "61412345678",
            {
              "number": "61498765432",
              "name": "Mary",
              "note": "Unsubscribed in our CRM"
            }
          ]
        },
        "number": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "DoNotCallAddResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "added": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "already_on_list": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "count": {
          "type": "integer",
          "description": "Numbers on the list now."
        }
      }
    },
    "DoNotCallRemoveResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "removed": {
          "type": "boolean",
          "description": "false: it was not on the list."
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "WebhookRequest": {
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "example": "https://hooks.example.com/app2email",
          "description": "Public https address that accepts POST. No redirects."
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "deprecated": true,
          "description": "Not used: every webhook gets every event. Accepted (and ignored) so older clients keep working."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Up to 5 custom headers sent with every event, eg {\"Authorization\": \"Basic dXNlcjpwYXNz\"}. Values: printable ASCII, one line. Not allowed: Host, User-Agent, Content-*, X-App2email-*, X-Hub-*, Proxy-*, X-Forwarded-* and connection headers. Answers (also a test's sent_headers) show each value as its last 4 characters.",
          "example": {
            "Authorization": "Basic dXNlcjpwYXNz"
          }
        },
        "format": {
          "type": "string",
          "enum": [
            "app2email",
            "meta"
          ],
          "default": "app2email",
          "description": "The body format, not an event choice: every webhook still gets every event. meta: what comes from WhatsApp is sent as Meta's own webhook body ({object, entry[].changes[]}, as Meta sent it; X-App2email-Event: meta.<field>), one POST per change, instead of its events (message.*, contact.opted_out, contact.changed_number, number.*, template.status_changed, WhatsApp's handovers and marketing_resumed). app2email's own events (broadcast.completed, usage.threshold, approvals, contact changes made in app2email ...) keep the envelope. Signed the same way."
        }
      }
    },
    "WebhookPatchRequest": {
      "type": "object",
      "description": "Change any of them. Only what is given changes.",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "example": "https://hooks.example.com/app2email-v2",
          "description": "Public https address that accepts POST. No redirects."
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "deprecated": true,
          "description": "Not used: every webhook gets every event. A PATCH with only events answers 200 with the webhook unchanged."
        },
        "active": {
          "type": "boolean",
          "description": "true: turn the webhook on again (after it was switched off for failures). false: turn it off."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Up to 5 custom headers sent with every event, eg {\"Authorization\": \"Basic dXNlcjpwYXNz\"}. Values: printable ASCII, one line. Not allowed: Host, User-Agent, Content-*, X-App2email-*, X-Hub-*, Proxy-*, X-Forwarded-* and connection headers. Answers (also a test's sent_headers) show each value as its last 4 characters. A header set to null is removed; \"headers\": null removes them all.",
          "example": {
            "Authorization": "Basic dXNlcjpwYXNz"
          }
        },
        "format": {
          "type": "string",
          "enum": [
            "app2email",
            "meta"
          ],
          "default": "app2email",
          "description": "The body format, not an event choice: every webhook still gets every event. meta: what comes from WhatsApp is sent as Meta's own webhook body ({object, entry[].changes[]}, as Meta sent it; X-App2email-Event: meta.<field>), one POST per change, instead of its events (message.*, contact.opted_out, contact.changed_number, number.*, template.status_changed, WhatsApp's handovers and marketing_resumed). app2email's own events (broadcast.completed, usage.threshold, approvals, contact changes made in app2email ...) keep the envelope. Signed the same way."
        }
      }
    },
    "Webhook": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "wh_a1b2c3d4e5f6g7h8"
        },
        "url": {
          "type": "string"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Every event type: every webhook gets every event."
        },
        "secret": {
          "type": "string",
          "description": "Signs every event: X-App2email-Signature and X-Hub-Signature-256. New one from POST .../rotate-secret."
        },
        "previous_secret_until": {
          "type": "string",
          "format": "date-time",
          "description": "After rotate-secret with keep_old_for_hours: the old secret also signs (a second v1= in X-App2email-Signature) until then."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "active": {
          "type": "boolean",
          "description": "false: switched off (see disabled_reason). Turn it on with PATCH active: true."
        },
        "disabled_reason": {
          "type": "string",
          "description": "Why it is off, eg after too many failed deliveries in a row, or 'turned off by you'."
        },
        "last_delivery": {
          "type": "object",
          "properties": {
            "at": {
              "type": "string",
              "format": "date-time"
            },
            "ok": {
              "type": "boolean"
            },
            "result": {
              "type": "string"
            }
          }
        },
        "format": {
          "type": "string",
          "enum": [
            "app2email",
            "meta"
          ],
          "default": "app2email",
          "description": "The body format, not an event choice: every webhook still gets every event. meta: what comes from WhatsApp is sent as Meta's own webhook body ({object, entry[].changes[]}, as Meta sent it; X-App2email-Event: meta.<field>), one POST per change, instead of its events (message.*, contact.opted_out, contact.changed_number, number.*, template.status_changed, WhatsApp's handovers and marketing_resumed). app2email's own events (broadcast.completed, usage.threshold, approvals, contact changes made in app2email ...) keep the envelope. Signed the same way."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "The custom headers, each value as its last 4 characters.",
          "example": {
            "Authorization": "****YXNz"
          }
        }
      }
    },
    "WebhookDelivery": {
      "type": "object",
      "description": "One event sent (or tried) to a webhook. Kept 7 days, the latest 100 per webhook.",
      "properties": {
        "event_id": {
          "type": "string",
          "example": "evt_Xq3..."
        },
        "type": {
          "type": "string",
          "example": "message.status"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "delivered": {
          "type": "boolean",
          "description": "true: your URL answered 2xx."
        },
        "attempts": {
          "type": "array",
          "description": "Every try, in order.",
          "items": {
            "type": "object",
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "ok": {
                "type": "boolean"
              },
              "http_status": {
                "type": "integer"
              },
              "ms": {
                "type": "integer"
              },
              "error": {
                "type": "string"
              }
            }
          }
        },
        "event_body": {
          "$ref": "#/definitions/WebhookEvent",
          "description": "Only in GET .../deliveries/{event_id}: the event exactly as sent."
        },
        "next_attempt_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the next try is planned, while one is (tries after 10 s, 1 min, 5 min, 30 min, 1, 2, 4, 8, 16 h)."
        }
      }
    },
    "WebhookDeliveriesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deliveries": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/WebhookDelivery"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "WebhookDeliveryResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "delivery": {
          "$ref": "#/definitions/WebhookDelivery"
        }
      }
    },
    "WebhookRedeliverResponse": {
      "type": "object",
      "description": "The stored event sent again (same event id). See WebhookTestResponse for the fields.",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "delivered": {
          "type": "boolean"
        },
        "http_status": {
          "type": "integer"
        },
        "response_ms": {
          "type": "integer"
        },
        "error": {
          "type": "string"
        }
      }
    },
    "WebhookResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "webhook": {
          "$ref": "#/definitions/Webhook"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "WebhooksResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "events_available": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "webhooks": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Webhook"
          }
        }
      }
    },
    "WebhookDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "string"
        }
      }
    },
    "WebhookTestResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "delivered": {
          "type": "boolean",
          "description": "Your URL answered 2xx within 10 seconds."
        },
        "http_status": {
          "type": "integer"
        },
        "response_ms": {
          "type": "integer"
        },
        "error": {
          "type": "string"
        },
        "response_body": {
          "type": "string",
          "description": "The start of what your URL answered (up to 1000 characters)."
        },
        "sent_headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "The headers sent, signatures included."
        },
        "sent_event": {
          "$ref": "#/definitions/WebhookEvent"
        },
        "sent_body": {
          "type": "string",
          "description": "The body exactly as sent (and signed)."
        }
      }
    },
    "WebhookTestRequest": {
      "type": "object",
      "description": "Optional. No body: a ping. type: that event's sample (GET .../webhooks/samples). event: the event you give, as it is (a missing id, created or number is filled in).",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "ping",
            "message.status",
            "message.received",
            "message.failed",
            "contact.opted_out",
            "broadcast.completed",
            "usage.threshold",
            "template.status_changed",
            "conversation.owner_changed",
            "message.held_for_approval",
            "approval.resolved",
            "contact.updated",
            "waitlist.joined",
            "waitlist.notified",
            "waitlist.removed",
            "booking.created",
            "booking.cancelled",
            "booking.rescheduled",
            "booking.rated",
            "flow.completed",
            "booking.updated",
            "booking.note.created",
            "calendar.block.created",
            "calendar.block.deleted",
            "call.incoming",
            "call.status",
            "message.edited",
            "message.deleted",
            "contact.changed_number",
            "number.updated",
            "number.error",
            "flow.status_changed",
            "client.created",
            "client.updated",
            "client.suspended",
            "number.created",
            "number.ready",
            "number.disconnected",
            "number.reconnected",
            "subscription.created",
            "subscription.renewed",
            "subscription.payment_failed",
            "subscription.cancelled",
            "trial.ending",
            "trial.expired",
            "plan.limit_reached",
            "api_key.created",
            "api_key.revoked",
            "booking.paid",
            "booking.refunded",
            "payment.paid",
            "package.purchased",
            "poll.voted",
            "poll.closed",
            "booking.customer.erased",
            "order.created",
            "order.paid",
            "order.accepted",
            "order.ready",
            "order.completed",
            "order.cancelled",
            "order.refunded",
            "order.no_show",
            "submission.created",
            "submission.files_ready",
            "submission.updated",
            "submission.status_changed",
            "submission.assigned",
            "submission.note_added",
            "submission.customer_replied",
            "submission.deleted",
            "submit.automation_failed",
            "ticket.order.confirmed",
            "ticket.order.refunded",
            "ticket.checked_in",
            "ticket.passed_on",
            "ticket.event.sold_out",
            "ticket.event.cancelled",
            "ticket.waitlist.joined",
            "ticket.buyer.erased"
          ],
          "example": "message.received"
        },
        "event": {
          "$ref": "#/definitions/WebhookEvent"
        }
      }
    },
    "WebhookRotateRequest": {
      "type": "object",
      "description": "Optional. No body: the old secret stops at once.",
      "properties": {
        "keep_old_for_hours": {
          "type": "integer",
          "minimum": 0,
          "maximum": 24,
          "example": 24,
          "description": "The old secret keeps signing too (a second v1= in X-App2email-Signature) for this many hours."
        }
      }
    },
    "WebhookSamplesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "samples": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/WebhookEvent"
          },
          "description": "Event type -> a sample event, as a test sends it."
        },
        "note": {
          "type": "string"
        },
        "meta_samples": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "Event type -> what a webhook with format meta gets instead (only the events that come from WhatsApp)."
        }
      }
    },
    "WebhookEvent": {
      "type": "object",
      "description": "What app2email POSTs to your webhook URL. Headers: X-App2email-Event (the type), X-App2email-Delivery (the id), X-App2email-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the webhook's secret> (a second v1= while an old secret is kept), X-Hub-Signature-256: sha256=<hex HMAC-SHA256 of the raw body with the webhook's secret> (as Meta signs WhatsApp webhooks), and on test events X-App2email-Test: true.",
      "properties": {
        "id": {
          "type": "string",
          "example": "evt_Xq3..."
        },
        "type": {
          "type": "string",
          "enum": [
            "message.status",
            "message.received",
            "message.failed",
            "contact.opted_out",
            "broadcast.completed",
            "usage.threshold",
            "template.status_changed",
            "conversation.owner_changed",
            "message.held_for_approval",
            "approval.resolved",
            "contact.updated",
            "waitlist.joined",
            "waitlist.notified",
            "waitlist.removed",
            "booking.created",
            "booking.cancelled",
            "booking.rescheduled",
            "booking.rated",
            "flow.completed",
            "booking.updated",
            "booking.note.created",
            "calendar.block.created",
            "calendar.block.deleted",
            "call.incoming",
            "call.status",
            "message.edited",
            "message.deleted",
            "contact.changed_number",
            "number.updated",
            "number.error",
            "flow.status_changed",
            "client.created",
            "client.updated",
            "client.suspended",
            "number.created",
            "number.ready",
            "number.disconnected",
            "number.reconnected",
            "subscription.created",
            "subscription.renewed",
            "subscription.payment_failed",
            "subscription.cancelled",
            "trial.ending",
            "trial.expired",
            "plan.limit_reached",
            "api_key.created",
            "api_key.revoked",
            "booking.paid",
            "booking.refunded",
            "payment.paid",
            "package.purchased",
            "poll.voted",
            "poll.closed",
            "booking.customer.erased",
            "order.created",
            "order.paid",
            "order.accepted",
            "order.ready",
            "order.completed",
            "order.cancelled",
            "order.refunded",
            "order.no_show",
            "submission.created",
            "submission.files_ready",
            "submission.updated",
            "submission.status_changed",
            "submission.assigned",
            "submission.note_added",
            "submission.customer_replied",
            "submission.deleted",
            "submit.automation_failed",
            "ticket.order.confirmed",
            "ticket.order.refunded",
            "ticket.checked_in",
            "ticket.passed_on",
            "ticket.event.sold_out",
            "ticket.event.cancelled",
            "ticket.waitlist.joined",
            "ticket.buyer.erased",
            "ping"
          ]
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "number": {
          "type": "string",
          "description": "Your WhatsApp number."
        },
        "test": {
          "type": "boolean",
          "description": "Only on test events (POST .../test): true."
        },
        "data": {
          "type": "object",
          "additionalProperties": true,
          "description": "message.status: {message_id, to, status (sent|delivered|read|played|clicked|failed|deleted), timestamp, error {code, message, title, details, error_code, how_to_fix, is_retriable, retry_after_seconds}, sent_by, broadcast_code, whatsapp_status, pricing, callback_data, recipient_user_id, recipient_identity_key_hash, whatsapp}. message.failed: the same data as message.status with status failed. message.received: {message_id, from, from_user_id, media_url, name, type, text, button {text, payload}, in_reply_to, conversation_url, timestamp, context, referral, location, contacts, reaction, interactive, flow, order, identity_key_hash, whatsapp (Meta's message object)}. contact.opted_out: {number, name, source (stop_promotions|whatsapp_stop), detail, timestamp}. broadcast.completed: {code, name, status (completed|cancelled|missed), sent_by, numbers, posted, accepted, errors, skipped_do_not_call, skipped_monthly_limit, status_url, report_url}. usage.threshold: {threshold_percent (80|100), whatsapp_messages {used, limit, left}, plan_messages {whatsapp_sent, emails_sent, total_sent, limit, left}, plan, billing_period {start, end}, timestamp}. template.status_changed: {template {name, language, id}, status (APPROVED|PENDING|REJECTED|PAUSED|DISABLED|COMPONENTS_UPDATED ...), change (a Meta field, or components: the template was edited), previous_value, new_value, components, reason, can_send, timestamp}. conversation.owner_changed: {contact, owner, previous_owner, reason, summary, until, set_by, timestamp}. message.held_for_approval: {approval_id, url, approve_url, recipients, key, summary, expires, timestamp}. approval.resolved: {approval_id, status (approved|rejected|expired), resolved_by, result {status, accepted, failed, broadcast_code}, timestamp}. contact.updated: {contact (a Contact), change (upsert|patch|consent|marketing_resumed), timestamp}. booking.created / booking.cancelled / booking.rescheduled / booking.rated: the Booking object (id, reference, status, contact, contact_name, service {id, name, duration_min}, start, end, timezone, source, calendar {provider, event_id, url, error}, answers, notes, provider {id, name}, rating, payment_status, credits_used, attendance_confirmed, cancelled {at, by, reason}, rescheduled_from_id, link_id, created) plus timestamp; booking.created also hold (true when made from a held time); booking.rescheduled also rescheduled_from {id, reference, start, end}; booking.rated also rated_at. flow.completed: {flow_key, flow_name, contact, contact_name, session_id, answers {field: text}, timestamp}. booking.updated: the Booking object plus changed [name | email | notes | answers | provider] and updated_by. booking.note.created: the Note {id, contact, appointment_id, booking_reference, body, author, author_kind, pinned, created, updated} plus booking {id, reference} (null when on the customer alone). calendar.block.created / calendar.block.deleted: the Block {id, provider_id, title, notes, start, end, start_local, end_local, source, created_by, created, updated} plus by. booking.paid / booking.refunded: the Booking object plus payment {the Payment}; booking.refunded also refund {amount, amount_label, full, by}. payment.paid: {payment, timestamp}. package.purchased: {purchase, payment, granted, timestamp}. poll.voted: {poll_id, title, name, contact, email, choices, comment}. poll.closed: {poll_id, title, status closed | booked, chosen_option, appointment_id, by}. booking.customer.erased: {contact, counts}. submission.created / submission.files_ready / submission.updated / submission.status_changed / submission.assigned / submission.note_added / submission.customer_replied / submission.deleted: the Submission object (id, reference, form {key, name}, channel, status, status_name, status_kind, status_color, priority, tags, due, assignee {id, name}, contact {identity, name, phone, email, verified}, conversation_id, answers {field: value}, extra, location, parent, summary, files_count, files_pending, unread, link, created, updated, status_changed, closed, files, buttons); submission.updated, submission.status_changed and submission.assigned also change {status {from, to}, assignee {from, to}, answers, priority, tags, due, location, files {added}, verified, note, by}; submission.note_added also note and by; submission.customer_replied also reply {text, files, button, followup}; submission.deleted also erased (an erased submission keeps only id, reference, form, channel, status, status_kind, created). submit.automation_failed: the Submission object (without files and buttons) plus automation {id, name}, step, error. waitlist.joined: {id, reference, status, service_id, service_name, provider_id, provider_name, date, date_label, slot_id, time_label, contact, contact_name, contact_email, seats, source, notified_count, notified_at, appointment_id, note, created, updated, day, slot_local, contact_masked, created_at, by, timestamp}. waitlist.notified: {id, reference, status, service_id, service_name, provider_id, provider_name, date, date_label, slot_id, time_label, contact, contact_name, contact_email, seats, source, notified_count, notified_at, appointment_id, note, created, updated, day, slot_local, contact_masked, created_at, offer, timestamp}. waitlist.removed: {id, reference, status, service_id, service_name, provider_id, provider_name, date, date_label, slot_id, time_label, contact, contact_name, contact_email, seats, source, notified_count, notified_at, appointment_id, note, created, updated, day, slot_local, contact_masked, created_at, by, timestamp}. call.incoming: {call_id, status, direction, event, from, from_user_id, to, to_user_id, contact, session, start_time, end_time, duration_seconds, biz_opaque_callback_data, error, recording, transcription, timestamp, whatsapp}. call.status: {call_id, status, direction, event, from, from_user_id, to, to_user_id, contact, session, start_time, end_time, duration_seconds, biz_opaque_callback_data, error, recording, transcription, timestamp, whatsapp}. message.edited: {message_id, original_message_id, from, from_user_id, name, type, text, message, conversation_url, timestamp, whatsapp}. message.deleted: {message_id, original_message_id, from, from_user_id, name, conversation_url, timestamp, whatsapp}. contact.changed_number: {change, previous, new, name, body, message_id, conversation_url, timestamp, whatsapp}. number.updated: {change, previous_value, new_value, details, next_step, whatsapp_field, timestamp}. number.error: {code, title, message, details, href, error_code, how_to_fix, is_retriable, retry_after_seconds, timestamp}. flow.status_changed: {flow_id, change, event, old_status, new_status, message, warning, alert_state, threshold, error_rate, p50_latency, p90_latency, availability, requests_count, errors, timestamp}. client.created: {client, source, changes, timestamp}. client.updated: {client, source, changes, timestamp}. client.suspended: {client, source, changes, timestamp}. number.created: {number, client_id, timestamp, name, display_number, service_status, plan}. number.ready: {number, client_id, timestamp, name, service_status, plan}. number.disconnected: {number, client_id, timestamp, reason, next_step, details}. number.reconnected: {number, client_id, timestamp, reason, details}. subscription.created: {subscription, timestamp}. subscription.renewed: {subscription, timestamp}. subscription.payment_failed: {subscription, timestamp}. subscription.cancelled: {subscription, timestamp}. trial.ending: {number, client_id, timestamp, trial_ends_at, days_left, plan_messages}. trial.expired: {number, client_id, timestamp, trial_ended_at, service_status}. plan.limit_reached: {number, client_id, timestamp, plan, plan_messages, billing_period}. api_key.created: {number, client_id, timestamp, key, created_by}. api_key.revoked: {number, client_id, timestamp, key, revoked_by}. order.created: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp}. order.paid: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp}. order.accepted: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp}. order.ready: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp}. order.completed: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp, handover}. order.cancelled: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp, cancelled}. order.refunded: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp, refund}. order.no_show: {reference, status, source, fulfilment, asap, due, customer, items, items_count, currency, subtotal, discount, discount_code, delivery_fee, fees, tip, tax, total, total_label, refunded, payment, delivery, note, allergy_note, pickup_code, created, timestamp, no_show}. ticket.order.confirmed: {order, timestamp}. ticket.order.refunded: {order, refund, timestamp}. ticket.checked_in: {ticket, order, check_in, timestamp}. ticket.passed_on: {ticket, previous_ticket_id, order, timestamp}. ticket.event.sold_out: {event, date, sold, timestamp}. ticket.event.cancelled: {event, date, scope, refund, reason, orders, tickets, refunded, refunded_label, refunds_failed, timestamp}. ticket.waitlist.joined: {entry, event, timestamp}. ticket.buyer.erased: {contact, counts, timestamp}. ping: {webhook_id, message}."
        }
      }
    },
    "TemplatesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "from": {
          "type": "string",
          "example": "4976659348270"
        },
        "send_url": {
          "type": "string",
          "example": "https://api.app2email.com/v1/4976659348270/messages"
        },
        "templates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TemplateInfo"
          }
        }
      }
    },
    "TemplateInfo": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "language": {
          "type": "string"
        },
        "category": {
          "type": "string",
          "example": "UTILITY"
        },
        "status": {
          "type": "string",
          "example": "APPROVED",
          "description": "APPROVED, PENDING, REJECTED, PAUSED, DISABLED ..."
        },
        "id": {
          "type": "string",
          "description": "WhatsApp's id of the template (in GET /templates/{name})."
        },
        "rejected_reason": {
          "type": "string",
          "description": "Why WhatsApp rejected it. Left out when there is none."
        },
        "quality_score": {
          "type": "string",
          "enum": [
            "GREEN",
            "YELLOW",
            "RED"
          ],
          "description": "WhatsApp's quality rating from the contacts' reactions. Left out when unknown. A RED template can be paused by WhatsApp."
        },
        "can_send": {
          "type": "boolean",
          "description": "Only APPROVED templates can be sent."
        },
        "needs": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "What values the template needs, in words."
        },
        "example_request": {
          "$ref": "#/definitions/SendTemplateRequest"
        },
        "sub_category": {
          "type": "string"
        },
        "previous_category": {
          "type": "string",
          "description": "The category before Meta changed it."
        },
        "correct_category": {
          "type": "string",
          "description": "The category Meta says is right."
        },
        "parameter_format": {
          "type": "string"
        },
        "message_send_ttl_seconds": {
          "type": "integer"
        },
        "cta_url_link_tracking_opted_out": {
          "type": "boolean"
        },
        "is_primary_device_delivery_only": {
          "type": "boolean"
        },
        "library_template_name": {
          "type": "string",
          "description": "Set when the template came from the Template Library."
        }
      }
    },
    "TemplateDetailResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "versions": {
          "type": "array",
          "description": "One entry per language of the template.",
          "items": {
            "$ref": "#/definitions/TemplateInfo"
          }
        }
      }
    },
    "TemplateCreateRequest": {
      "type": "object",
      "required": [
        "name",
        "language",
        "category"
      ],
      "description": "The template as WhatsApp's API takes it. Meta's template rules apply (placeholders {{1}}, sample values in 'example').",
      "properties": {
        "name": {
          "type": "string",
          "example": "order_update",
          "description": "Lowercase letters, digits and underscores."
        },
        "language": {
          "type": "string",
          "example": "en"
        },
        "category": {
          "type": "string",
          "enum": [
            "MARKETING",
            "UTILITY",
            "AUTHENTICATION"
          ],
          "example": "UTILITY"
        },
        "components": {
          "type": "array",
          "description": "WhatsApp's components: BODY (text), HEADER, FOOTER, BUTTONS. Required unless library_template_name is given.",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "example": [
            {
              "type": "BODY",
              "text": "Hi {{1}}, your order {{2}} has shipped.",
              "example": {
                "body_text": [
                  [
                    "John",
                    "#1234"
                  ]
                ]
              }
            }
          ]
        },
        "parameter_format": {
          "type": "string",
          "enum": [
            "NAMED",
            "POSITIONAL"
          ],
          "description": "NAMED ({{first_name}}) or POSITIONAL ({{1}}) placeholders."
        },
        "allow_category_change": {
          "type": "boolean",
          "description": "Passed on; Meta ignores it since 9 Apr 2025 (it sets the category itself)."
        },
        "message_send_ttl_seconds": {
          "type": "integer",
          "description": "How long WhatsApp tries to deliver (Meta's ranges per category)."
        },
        "cta_url_link_tracking_opted_out": {
          "type": "boolean",
          "description": "true: no click tracking on URL buttons."
        },
        "is_primary_device_delivery_only": {
          "type": "boolean"
        },
        "sub_category": {
          "type": "string",
          "example": "ORDER_STATUS"
        },
        "display_format": {
          "type": "string",
          "example": "ORDER_DETAILS"
        },
        "degrees_of_freedom_spec": {
          "type": "object",
          "additionalProperties": true,
          "description": "Marketing creative options, as Meta takes them."
        },
        "send_type": {
          "type": "string",
          "enum": [
            "campaign",
            "direct"
          ],
          "description": "Marketing Messages API templates."
        },
        "optimization_spec": {
          "$ref": "#/definitions/OptimizationSpec"
        },
        "library_template_name": {
          "type": "string",
          "example": "delivery_update_1",
          "description": "Create from the Template Library (GET /template-library); then no components."
        },
        "library_template_button_inputs": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "example": [
            {
              "type": "URL",
              "url": {
                "base_url": "https://www.example.com/{{1}}",
                "url_suffix_example": "https://www.example.com/order/1234"
              }
            }
          ],
          "description": "Library templates with buttons: the website and phone number."
        },
        "library_template_body_inputs": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "add_contact_number": true
          }
        }
      }
    },
    "TemplateCreateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "template": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "category": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "example": "PENDING"
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplateDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "string",
          "example": "order_update"
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FreeFormText": {
      "type": "object",
      "required": [
        "body"
      ],
      "properties": {
        "body": {
          "type": "string",
          "example": "Thanks, it arrives on Friday.",
          "description": "The text. Up to 4096 characters."
        },
        "preview_url": {
          "type": "boolean",
          "default": false,
          "description": "true: show a preview of a link in the text."
        }
      }
    },
    "FreeFormMedia": {
      "type": "object",
      "description": "Give exactly one of: link, data or id. 'filename' is shown to the recipient for documents.",
      "properties": {
        "link": {
          "type": "string",
          "format": "uri",
          "example": "https://example.com/photo.jpg",
          "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
        },
        "id": {
          "type": "string",
          "description": "A media id from POST /media (or uploaded to WhatsApp for this number)."
        },
        "filename": {
          "type": "string",
          "example": "invoice.pdf",
          "description": "Needed with 'data' for documents."
        },
        "mime_type": {
          "type": "string",
          "example": "application/pdf",
          "description": "Optional. The type is detected from the file where possible."
        },
        "caption": {
          "type": "string",
          "maxLength": 1024,
          "example": "Your parcel",
          "description": "Optional text under the image, video or document."
        }
      }
    },
    "MediaUploadRequest": {
      "type": "object",
      "required": [
        "type",
        "file"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "image",
            "video",
            "document",
            "audio",
            "sticker"
          ]
        },
        "file": {
          "type": "object",
          "description": "Give 'link' (a public URL) or base64 'data'. 'filename' for documents.",
          "properties": {
            "link": {
              "type": "string",
              "format": "uri",
              "example": "https://example.com/photo.jpg"
            },
            "data": {
              "type": "string",
              "format": "byte"
            },
            "filename": {
              "type": "string",
              "example": "invoice.pdf"
            },
            "mime_type": {
              "type": "string",
              "example": "application/pdf",
              "description": "Optional. The type is detected from the file where possible."
            },
            "voice": {
              "type": "boolean",
              "description": "Audio: check it is a voice message (Ogg with OPUS)."
            }
          }
        }
      }
    },
    "MediaUploadResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "media_id": {
          "type": "string",
          "example": "1234567890"
        },
        "type": {
          "type": "string"
        },
        "filename": {
          "type": "string"
        },
        "info": {
          "type": "object",
          "additionalProperties": true
        },
        "expires_in_days": {
          "type": "integer",
          "example": 30
        },
        "note": {
          "type": "string"
        },
        "sandbox": {
          "type": "boolean",
          "description": "true: a sandbox key; the file was checked, nothing uploaded, media_id is made up (sandbox sends accept it)."
        }
      }
    },
    "MeResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "key_valid": {
          "type": "boolean",
          "example": true
        },
        "api_version": {
          "type": "string",
          "example": "v1"
        },
        "number": {
          "type": "string"
        },
        "plan": {
          "type": "string",
          "example": "standard_5000"
        },
        "service_status": {
          "type": "string",
          "example": "LIVE"
        },
        "key": {
          "type": "object",
          "description": "The key used for this call.",
          "properties": {
            "name": {
              "type": "string",
              "example": "Zapier"
            },
            "scopes": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "messages:read",
                "messages:send"
              ],
              "description": "'*' = full access."
            },
            "expires": {
              "type": "string",
              "format": "date-time",
              "description": "Left out when the key never expires."
            },
            "ip_allow": {
              "type": "string",
              "description": "The addresses it may be used from, comma separated. '' = any."
            },
            "sandbox": {
              "type": "boolean",
              "description": "true: a sandbox key, sends are simulated."
            },
            "daily_cap": {
              "type": "integer",
              "description": "Most messages per UTC day. Left out when there is no cap."
            },
            "daily_used": {
              "type": "integer",
              "description": "Messages counted against the daily cap today."
            },
            "approval_above": {
              "type": "integer",
              "description": "Sends to more contacts than this are held for approval. Left out when there is no gate."
            }
          }
        },
        "sandbox": {
          "type": "boolean",
          "description": "true when the key is a sandbox key (left out otherwise)."
        },
        "limits": {
          "type": "object",
          "properties": {
            "max_numbers_per_request": {
              "type": "integer"
            },
            "requests_per_second": {
              "type": "integer"
            },
            "burst": {
              "type": "integer"
            },
            "rate_limit_mode": {
              "type": "string",
              "enum": [
                "log_only",
                "enforce",
                "off"
              ]
            },
            "webhooks_max": {
              "type": "integer"
            },
            "monthly_cap": {
              "type": "integer",
              "description": "The number's own monthly cap (settings caps.monthly_messages). Left out when there is none."
            }
          }
        },
        "conversation_owner_values": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "",
            "agent",
            "human",
            "paused"
          ]
        },
        "scopes_available": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "RequestLogItem": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "example": "kxrkf"
        },
        "time": {
          "type": "string",
          "format": "date-time"
        },
        "method": {
          "type": "string",
          "example": "POST"
        },
        "route": {
          "type": "string",
          "example": "/v1/4976659348270/messages"
        },
        "status": {
          "type": "integer",
          "example": 422
        },
        "ms": {
          "type": "integer",
          "example": 412
        },
        "key": {
          "type": "string",
          "example": "Zapier",
          "description": "The key's name, or 'Default key'."
        },
        "ip": {
          "type": "string",
          "example": "203.0.113.7"
        }
      }
    },
    "RequestsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "requests": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/RequestLogItem"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "RequestResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "request": {
          "$ref": "#/definitions/RequestLogItem"
        }
      }
    },
    "MessageListItem": {
      "type": "object",
      "description": "direction 'out': a message sent from the number (the MessageInfo fields, plus time). direction 'in': a contact's message (from, name, text, media).",
      "properties": {
        "direction": {
          "type": "string",
          "enum": [
            "in",
            "out"
          ]
        },
        "message_id": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA="
        },
        "to": {
          "type": "string",
          "example": "61412345678",
          "description": "direction out."
        },
        "from": {
          "type": "string",
          "example": "61412345678",
          "description": "direction in: the contact's number, or their business-scoped user id when no number is known."
        },
        "from_user_id": {
          "type": "string",
          "description": "direction in: the contact's business-scoped user id, when WhatsApp sent one."
        },
        "media_url": {
          "type": "string",
          "description": "direction in, media messages: app2email's stored copy (GET /media/{message_id}, with your key). WhatsApp's own media ids expire after 7 days."
        },
        "name": {
          "type": "string",
          "description": "direction in: the contact's name."
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "accepted",
            "sent",
            "delivered",
            "read",
            "failed",
            "deleted",
            "unknown"
          ],
          "description": "direction out."
        },
        "sent_by": {
          "type": "string"
        },
        "broadcast_code": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "media": {
          "type": "string"
        },
        "time": {
          "type": "string",
          "format": "date-time"
        },
        "times": {
          "$ref": "#/definitions/MessageTimes",
          "description": "direction out."
        },
        "error": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string"
            }
          },
          "description": "direction out, when it failed."
        },
        "reply": {
          "type": "object",
          "description": "direction out: the contact's reply."
        },
        "conversation_url": {
          "type": "string"
        }
      }
    },
    "MessagesListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "messages": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MessageListItem"
          }
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "ConversationItem": {
      "type": "object",
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The phone number, or the business-scoped user id when no number is known."
        },
        "user_id": {
          "type": "string",
          "description": "The contact's business-scoped user id, when WhatsApp sent one."
        },
        "name": {
          "type": "string"
        },
        "last_inbound": {
          "type": "string",
          "format": "date-time"
        },
        "last_outbound": {
          "type": "string",
          "format": "date-time"
        },
        "window_open": {
          "type": "boolean",
          "description": "true: a free-form reply can be sent now (24 hour window)."
        },
        "window_closes_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the window closes (only while it is open)."
        },
        "owner": {
          "type": "string",
          "enum": [
            "agent",
            "human",
            "paused"
          ],
          "description": "Who handles the contact (PUT /conversations/{contact}/owner). Left out for the normal routing."
        },
        "messages": {
          "type": "integer"
        },
        "conversation_url": {
          "type": "string"
        }
      }
    },
    "ConversationsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "conversations": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ConversationItem"
          }
        },
        "next_cursor": {
          "type": "string"
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "ConversationMessagesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "contact": {
          "type": "string",
          "example": "61412345678"
        },
        "window_open": {
          "type": "boolean"
        },
        "window_closes_at": {
          "type": "string",
          "format": "date-time"
        },
        "owner": {
          "type": "string",
          "enum": [
            "agent",
            "human",
            "paused"
          ],
          "description": "Left out for the normal routing."
        },
        "messages": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MessageListItem"
          }
        },
        "next_cursor": {
          "type": "string"
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "UsageHistoryResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "months": {
          "type": "array",
          "description": "Newest first. Calendar months, UTC.",
          "items": {
            "type": "object",
            "properties": {
              "month": {
                "type": "string",
                "example": "2026-10"
              },
              "messages_sent": {
                "type": "integer"
              },
              "messages_failed": {
                "type": "integer"
              },
              "messages_received": {
                "type": "integer"
              },
              "broadcasts": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "StatsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        },
        "messages": {
          "type": "object",
          "description": "Sent messages in the range: submitted, accepted (WhatsApp took them), sent, delivered, read, failed, replied.",
          "properties": {
            "submitted": {
              "type": "integer"
            },
            "accepted": {
              "type": "integer"
            },
            "sent": {
              "type": "integer"
            },
            "delivered": {
              "type": "integer"
            },
            "read": {
              "type": "integer"
            },
            "failed": {
              "type": "integer"
            },
            "replied": {
              "type": "integer"
            }
          }
        },
        "received": {
          "type": "integer"
        },
        "rates": {
          "type": "object",
          "description": "Fractions: delivery = delivered / sent, read = read / delivered, reply = replied / sent.",
          "properties": {
            "delivery": {
              "type": "number"
            },
            "read": {
              "type": "number"
            },
            "reply": {
              "type": "number"
            }
          }
        },
        "truncated": {
          "type": "boolean",
          "description": "true: the range had too many messages, the counts are for part of it."
        }
      }
    },
    "BroadcastCancelResponse": {
      "type": "object",
      "description": "200: a scheduled broadcast was removed. 202: a broadcast that is sending now is being cancelled.",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "broadcast": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "cancelled",
                "cancelling"
              ]
            }
          }
        },
        "sent_before_cancel": {
          "type": "integer",
          "description": "200 only."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "AutoreplySettings": {
      "type": "object",
      "required": [
        "text"
      ],
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 4000,
          "example": "Thanks for writing! We reply within a day.",
          "description": "The first reply a new contact gets (the Default Auto Reply). 1 to 4000 characters. Auto Reply cards added on the dashboard (by date, day, time or keyword) are checked first; this text is used when none of them matches."
        }
      }
    },
    "AutoreplyResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ForwardingSettings": {
      "type": "object",
      "description": "Fields left out stay as they are. These are the Default forwarding addresses: Email Rules added on the dashboard (by date, day, time or keyword) are checked first, and the first one that matches decides where that message goes.",
      "properties": {
        "to": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          },
          "example": [
            "a@x.com"
          ],
          "description": "Up to 3 emails. Or a string: \"a@x.com, b@y.com\"."
        },
        "cc": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          },
          "example": [],
          "description": "Up to 3 emails."
        },
        "bcc": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          },
          "example": [],
          "description": "Up to 3 emails."
        },
        "text": {
          "type": "string",
          "example": "New WhatsApp message",
          "description": "The line put before each forwarded message."
        }
      }
    },
    "ForwardingResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "forwarding": {
          "type": "object",
          "properties": {
            "to": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "cc": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "bcc": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "text": {
              "type": "string"
            },
            "works_on_this_plan": {
              "type": "boolean",
              "description": "WhatsApp-to-email forwarding works on the Professional and Trial plans."
            },
            "plan": {
              "type": "string"
            }
          }
        },
        "note": {
          "type": "string",
          "description": "PUT only: when the plan does not support forwarding."
        }
      }
    },
    "OptinSettingRequest": {
      "type": "object",
      "required": [
        "require_optin_for_marketing"
      ],
      "properties": {
        "require_optin_for_marketing": {
          "type": "boolean",
          "description": "true: marketing templates are only sent to numbers with an opt-in record (others: recipient_not_opted_in). Utility templates are not affected. Off by default."
        }
      }
    },
    "OptinSettingResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "require_optin_for_marketing": {
          "type": "boolean"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "OptinItem": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string",
          "example": "61412345678"
        },
        "name": {
          "type": "string"
        },
        "source": {
          "type": "string",
          "example": "web form"
        },
        "note": {
          "type": "string"
        },
        "at": {
          "type": "string",
          "format": "date-time",
          "description": "When the person opted in."
        },
        "added_by": {
          "type": "string",
          "example": "api"
        }
      }
    },
    "OptinsAddRequest": {
      "type": "object",
      "required": [
        "numbers"
      ],
      "description": "Up to 1000 entries. All or nothing: one invalid entry, nothing is saved.",
      "properties": {
        "numbers": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "See the OpenAPI 3 description: one of several shapes.",
            "properties": {
              "number": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "note": {
                "type": "string"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "example": [
            "61412345678",
            {
              "number": "61498765432",
              "name": "Mary",
              "source": "web form",
              "note": "ticked the box",
              "at": "2026-10-01T00:00:00Z"
            }
          ],
          "description": "Numbers as strings, or objects with number, name, source, note and at (ISO 8601, when they opted in; default now)."
        }
      }
    },
    "OptinsAddResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "saved": {
          "type": "integer"
        }
      }
    },
    "OptinsListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "total": {
          "type": "integer"
        },
        "optins": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/OptinItem"
          }
        },
        "next_after": {
          "type": "string",
          "description": "Pass as 'after' for the next page. Left out on the last page and with ?number=."
        },
        "opted_in": {
          "type": "boolean",
          "description": "Only with ?number=: is this number opted in?"
        }
      }
    },
    "OptinRemoveResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "removed": {
          "type": "string",
          "example": "61412345678"
        }
      }
    },
    "Interactive": {
      "type": "object",
      "required": [
        "type",
        "action"
      ],
      "description": "WhatsApp's interactive object. type button: action.buttons, up to 3 reply buttons (title up to 20 characters; the shortcut \"buttons\": [\"Confirm\", \"Change\"] works too). type list: action.button (the text that opens the list) and action.sections with rows (up to 10 rows in all; a row can be a plain title). type cta_url: action.parameters {display_text, url}. header: text (60 characters), or image / video / document (link, data or id) for button and cta_url. body.text up to 1024 characters, footer.text up to 60. Also (WhatsApp Cloud API's objects): carousel (action.cards: 2 to 10, image or video header, one URL button or quick replies each; or product cards {card_index, type: 'product', action: {product_retailer_id, catalog_id}}), location_request_message, request_contact_info, flow (action.parameters: flow_message_version '3', flow_id or flow_name, flow_cta), product and product_list (a connected catalog), catalog_message, call_permission_request and voice_call (Calling), address_message (India; optional text header), order_details and order_status (payments). The fixed action.name of a kind is filled in when left out.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "button",
            "list",
            "cta_url",
            "carousel",
            "location_request_message",
            "request_contact_info",
            "flow",
            "product",
            "product_list",
            "catalog_message",
            "call_permission_request",
            "voice_call",
            "address_message",
            "order_details",
            "order_status"
          ]
        },
        "header": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "type": "text",
            "text": "Booking"
          }
        },
        "body": {
          "type": "object",
          "required": [
            "text"
          ],
          "properties": {
            "text": {
              "type": "string",
              "maxLength": 1024,
              "example": "Confirm your booking for Friday 10:00?"
            }
          }
        },
        "footer": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "maxLength": 60
            }
          }
        },
        "action": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "buttons": [
              {
                "type": "reply",
                "reply": {
                  "id": "yes",
                  "title": "Confirm"
                }
              },
              {
                "type": "reply",
                "reply": {
                  "id": "no",
                  "title": "Change"
                }
              }
            ]
          }
        }
      }
    },
    "ConversationDetail": {
      "type": "object",
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678"
        },
        "identity_type": {
          "type": "string",
          "enum": [
            "phone",
            "bsuid"
          ]
        },
        "phone": {
          "type": "string"
        },
        "user_id": {
          "type": "string",
          "description": "The business-scoped user id, when known."
        },
        "name": {
          "type": "string"
        },
        "window_state": {
          "type": "string",
          "enum": [
            "open",
            "closed"
          ],
          "description": "open: a free-form reply can be sent now."
        },
        "window_open": {
          "type": "boolean"
        },
        "window_closes_at": {
          "type": "string",
          "format": "date-time"
        },
        "last_inbound_at": {
          "type": "string",
          "format": "date-time"
        },
        "last_outbound_at": {
          "type": "string",
          "format": "date-time"
        },
        "messages": {
          "type": "integer"
        },
        "owner": {
          "type": "string",
          "enum": [
            "",
            "agent",
            "human",
            "paused"
          ],
          "description": "Who handles the contact now ('' = the number's normal routing; an owner_until in the past means '' again)."
        },
        "owner_set": {
          "type": "string",
          "description": "What was set, even when owner_until has passed."
        },
        "owner_set_at": {
          "type": "string",
          "format": "date-time"
        },
        "owner_set_by": {
          "type": "string",
          "example": "api:Support bot"
        },
        "owner_reason": {
          "type": "string"
        },
        "owner_summary": {
          "type": "string"
        },
        "owner_until": {
          "type": "string",
          "format": "date-time"
        },
        "held_replies": {
          "type": "boolean",
          "description": "Email replies are waiting for the contact to tap 'Show reply' (the 24 hour window had closed)."
        },
        "conversation_url": {
          "type": "string"
        }
      }
    },
    "ConversationDetailResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "contact": {
          "type": "string",
          "example": "61412345678"
        },
        "identity_type": {
          "type": "string",
          "enum": [
            "phone",
            "bsuid"
          ]
        },
        "phone": {
          "type": "string"
        },
        "user_id": {
          "type": "string",
          "description": "The business-scoped user id, when known."
        },
        "name": {
          "type": "string"
        },
        "window_state": {
          "type": "string",
          "enum": [
            "open",
            "closed"
          ],
          "description": "open: a free-form reply can be sent now."
        },
        "window_open": {
          "type": "boolean"
        },
        "window_closes_at": {
          "type": "string",
          "format": "date-time"
        },
        "last_inbound_at": {
          "type": "string",
          "format": "date-time"
        },
        "last_outbound_at": {
          "type": "string",
          "format": "date-time"
        },
        "messages": {
          "type": "integer"
        },
        "owner": {
          "type": "string",
          "enum": [
            "",
            "agent",
            "human",
            "paused"
          ],
          "description": "Who handles the contact now ('' = the number's normal routing; an owner_until in the past means '' again)."
        },
        "owner_set": {
          "type": "string",
          "description": "What was set, even when owner_until has passed."
        },
        "owner_set_at": {
          "type": "string",
          "format": "date-time"
        },
        "owner_set_by": {
          "type": "string",
          "example": "api:Support bot"
        },
        "owner_reason": {
          "type": "string"
        },
        "owner_summary": {
          "type": "string"
        },
        "owner_until": {
          "type": "string",
          "format": "date-time"
        },
        "held_replies": {
          "type": "boolean",
          "description": "Email replies are waiting for the contact to tap 'Show reply' (the 24 hour window had closed)."
        },
        "conversation_url": {
          "type": "string"
        }
      }
    },
    "OwnerRequest": {
      "type": "object",
      "required": [
        "owner"
      ],
      "properties": {
        "owner": {
          "type": "string",
          "enum": [
            "",
            "agent",
            "human",
            "paused"
          ],
          "description": "'' = the normal routing. human / paused: the auto reply and the A2A / OpenClaw agent leave this contact alone."
        },
        "reason": {
          "type": "string",
          "maxLength": 200,
          "example": "customer asked for a person"
        },
        "summary": {
          "type": "string",
          "maxLength": 2000,
          "description": "What the conversation is about so far, for the person taking over."
        },
        "until_minutes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 43200,
          "description": "After this many minutes the owner goes back to ''."
        }
      }
    },
    "OwnerResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "conversation": {
          "$ref": "#/definitions/ConversationDetail"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "NumberSettings": {
      "type": "object",
      "description": "The number's settings. GET answers every key with its default; PUT changes only the keys given (nested objects or dotted keys like \"email.mark_read_on_open\").",
      "properties": {
        "email": {
          "type": "object",
          "properties": {
            "delivery_receipts": {
              "type": "string",
              "enum": [
                "failed_only",
                "none",
                "all"
              ],
              "default": "failed_only",
              "description": "An email to the sender when their email reply failed on WhatsApp (or for every status)."
            },
            "mark_read_on_open": {
              "type": "boolean",
              "default": false,
              "description": "Send WhatsApp a read receipt when the forwarded email is opened."
            },
            "include_history": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100,
              "default": 20,
              "description": "Earlier messages of the conversation quoted under a forwarded message (the [HISTORY] block), at most 100. 0 = none and no Show All History button. 20 is what every number had before this setting existed. The dashboard offers 0, 10, 20, 50 and 100 (Chat History Summary)."
            },
            "history_images": {
              "type": "string",
              "enum": [
                "name",
                "link",
                "thumbnail"
              ],
              "default": "link",
              "description": "What goes under a photo the contact sent in that history. The photo's own line ([IMAGE, file name, type, size]) is always shown. name: nothing more. link: a line with the link to the full-size photo. thumbnail: a small picture linked to the full-size photo; it is loaded from that link, not attached to the email. A photo app2email has no copy of gets nothing more. The dashboard calls it Images in Chat History Summary."
            }
          }
        },
        "caps": {
          "type": "object",
          "properties": {
            "monthly_messages": {
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "description": "Your own monthly cap on outgoing messages (WhatsApp + email). 0 = the plan limit only."
            }
          }
        },
        "compliance": {
          "type": "object",
          "properties": {
            "adm_disclosure": {
              "type": "string",
              "maxLength": 500,
              "description": "Appended once to automated replies (auto reply, agents), eg 'This reply was generated automatically.'"
            },
            "stop_keywords_extra": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Your own opt-out words besides the built-in ones (STOP and its translations)."
            }
          }
        },
        "a2a": {
          "type": "object",
          "properties": {
            "respect_owner": {
              "type": "boolean",
              "default": true,
              "description": "Skip the A2A / OpenClaw agent when a conversation's owner is human or paused."
            }
          }
        },
        "messages": {
          "type": "object",
          "properties": {
            "marketing_route": {
              "type": "string",
              "enum": [
                "auto",
                "cloud_api",
                "mm_api"
              ],
              "default": "auto",
              "description": "Where MARKETING templates go: auto = the Marketing Messages API once WhatsApp says the account is onboarded, else the Cloud API; cloud_api; mm_api."
            }
          }
        }
      }
    },
    "NumberSettingsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "settings": {
          "$ref": "#/definitions/NumberSettings"
        },
        "keys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "Consent": {
      "type": "object",
      "description": "Consent to marketing messages, with the evidence the Spam Act 2003 expects you to keep.",
      "properties": {
        "marketing": {
          "type": "boolean",
          "description": "true: consented. false: withdrawn (add them to the Do Not Call list too)."
        },
        "at": {
          "type": "string",
          "format": "date-time",
          "description": "When. Now when left out."
        },
        "source": {
          "type": "string",
          "maxLength": 100,
          "example": "web form"
        },
        "text": {
          "type": "string",
          "maxLength": 1000,
          "example": "Yes, send me offers on WhatsApp",
          "description": "The wording the contact agreed to."
        },
        "evidence": {
          "type": "string",
          "maxLength": 500,
          "example": "https://example.com/forms/123",
          "description": "A link, file name, IP address or message id that proves it."
        }
      }
    },
    "ContactInput": {
      "type": "object",
      "description": "A contact to make or change. 'phone' (or 'identity': a number or a business-scoped user id) says which; the other fields given replace, the ones left out stay.",
      "properties": {
        "phone": {
          "type": "string",
          "example": "61412345678"
        },
        "identity": {
          "type": "string",
          "example": "61.AbC123xyz",
          "description": "Instead of phone: a number or a business-scoped user id."
        },
        "name": {
          "type": "string",
          "maxLength": 200,
          "example": "John Smith"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 40
          },
          "example": [
            "vip",
            "newsletter"
          ],
          "description": "Up to 50. A comma separated string works too."
        },
        "custom_fields": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "example": {
            "order_id": "1234",
            "first_name": "John"
          },
          "description": "Up to 50 text values (names: letters, digits, underscores). Used as named template values in segment sends."
        },
        "source": {
          "type": "string",
          "maxLength": 50,
          "example": "crm"
        },
        "consent": {
          "$ref": "#/definitions/Consent"
        }
      }
    },
    "Contact": {
      "type": "object",
      "properties": {
        "identity": {
          "type": "string",
          "example": "61412345678"
        },
        "identity_type": {
          "type": "string",
          "enum": [
            "phone",
            "bsuid"
          ]
        },
        "phone": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "custom_fields": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "source": {
          "type": "string"
        },
        "consent": {
          "type": "object",
          "properties": {
            "marketing": {
              "type": "boolean"
            },
            "at": {
              "type": "string",
              "format": "date-time"
            },
            "source": {
              "type": "string"
            },
            "text": {
              "type": "string"
            },
            "evidence": {
              "type": "string"
            },
            "recorded": {
              "type": "boolean",
              "description": "true when any consent record exists."
            }
          }
        },
        "last_inbound_at": {
          "type": "string",
          "format": "date-time"
        },
        "last_outbound_at": {
          "type": "string",
          "format": "date-time"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "ContactsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "contacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Contact"
          }
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        },
        "count": {
          "type": "integer"
        },
        "total": {
          "type": "integer"
        }
      }
    },
    "ContactResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "contact": {
          "$ref": "#/definitions/Contact"
        },
        "created": {
          "type": "boolean"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ContactsUpsertRequest": {
      "type": "object",
      "description": "One contact (ContactInput). A JSON array of them is accepted as well.",
      "properties": {
        "phone": {
          "type": "string",
          "example": "61412345678"
        },
        "identity": {
          "type": "string",
          "example": "61.AbC123xyz",
          "description": "Instead of phone: a number or a business-scoped user id."
        },
        "name": {
          "type": "string",
          "maxLength": 200,
          "example": "John Smith"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 40
          },
          "example": [
            "vip",
            "newsletter"
          ],
          "description": "Up to 50. A comma separated string works too."
        },
        "custom_fields": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "example": {
            "order_id": "1234",
            "first_name": "John"
          },
          "description": "Up to 50 text values (names: letters, digits, underscores). Used as named template values in segment sends."
        },
        "source": {
          "type": "string",
          "maxLength": 50,
          "example": "crm"
        },
        "consent": {
          "$ref": "#/definitions/Consent"
        }
      }
    },
    "ContactsUpsertResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "saved": {
          "type": "integer"
        },
        "created": {
          "type": "integer"
        },
        "updated": {
          "type": "integer"
        },
        "contacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Contact"
          },
          "description": "The first 100 as saved."
        }
      }
    },
    "ContactsImportResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "rows": {
          "type": "integer"
        },
        "saved": {
          "type": "integer"
        },
        "created": {
          "type": "integer"
        },
        "updated": {
          "type": "integer"
        },
        "skipped": {
          "type": "integer"
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "row": {
                "type": "integer"
              },
              "problem": {
                "type": "string"
              }
            }
          },
          "description": "The first 50 rows with a problem."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ContactDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SegmentFilter": {
      "type": "object",
      "description": "Which contacts a segment holds. Every condition given must hold.",
      "properties": {
        "tags_any": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "At least one of these tags."
        },
        "tags_all": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "All of these tags."
        },
        "consent_marketing": {
          "type": "boolean",
          "description": "true: only contacts with marketing consent. false: only without."
        },
        "last_inbound_days": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3650,
          "description": "Wrote to the number in the last N days."
        },
        "search": {
          "type": "string",
          "maxLength": 100,
          "description": "Part of the name or number."
        }
      }
    },
    "SegmentRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 100,
          "example": "VIP, consented"
        },
        "filter": {
          "$ref": "#/definitions/SegmentFilter"
        }
      }
    },
    "Segment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "example": 12
        },
        "name": {
          "type": "string"
        },
        "filter": {
          "$ref": "#/definitions/SegmentFilter"
        },
        "contacts": {
          "type": "integer",
          "description": "How many contacts match now (in answers that counted them)."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "SegmentsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "segments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Segment"
          }
        },
        "count": {
          "type": "integer"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SegmentResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "segment": {
          "$ref": "#/definitions/Segment"
        }
      }
    },
    "SegmentContactsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "segment": {
          "$ref": "#/definitions/Segment"
        },
        "contacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Contact"
          }
        },
        "next_cursor": {
          "type": "string"
        },
        "count": {
          "type": "integer"
        },
        "total": {
          "type": "integer"
        }
      }
    },
    "SegmentDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "MetaPricingCounts": {
      "type": "object",
      "properties": {
        "service_free_used": {
          "type": "integer"
        },
        "service_billable": {
          "type": "integer"
        },
        "utility": {
          "type": "integer"
        },
        "marketing": {
          "type": "integer"
        },
        "authentication": {
          "type": "integer"
        },
        "free_entry_point": {
          "type": "integer"
        },
        "unknown": {
          "type": "integer",
          "description": "No pricing information (yet)."
        },
        "total": {
          "type": "integer"
        },
        "estimated_cost_usd": {
          "type": "number"
        }
      }
    },
    "MetaPricing": {
      "type": "object",
      "description": "What WhatsApp (Meta) charges for the billing month's messages, from the pricing object of its status webhooks. Indicative: Meta bills you directly.",
      "properties": {
        "billing_period": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string",
              "format": "date-time"
            },
            "end": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "counts": {
          "$ref": "#/definitions/MetaPricingCounts"
        },
        "free_service_messages": {
          "type": "object",
          "properties": {
            "allowance_per_month": {
              "type": "integer",
              "example": 1000
            },
            "used": {
              "type": "integer"
            },
            "left": {
              "type": "integer"
            },
            "note": {
              "type": "string"
            }
          }
        },
        "estimated_cost": {
          "type": "object",
          "properties": {
            "currency": {
              "type": "string",
              "example": "USD"
            },
            "amount": {
              "type": "number"
            },
            "rate_region": {
              "type": "string"
            },
            "rate_region_code": {
              "type": "string"
            },
            "rates_per_message": {
              "type": "object",
              "additionalProperties": {
                "type": "number"
              }
            },
            "rates_last_checked": {
              "type": "string"
            },
            "note": {
              "type": "string"
            }
          }
        },
        "days": {
          "type": "array",
          "description": "GET /usage/meta only: per day.",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "example": "2026-11-02"
              },
              "counts": {
                "$ref": "#/definitions/MetaPricingCounts"
              }
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "UsageMetaResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "meta_pricing": {
          "$ref": "#/definitions/MetaPricing"
        }
      }
    },
    "Approval": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "apr_a1b2c3d4e5f6g7h8"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "approved",
            "rejected",
            "expired"
          ]
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "description": "48 hours after it was held."
        },
        "key": {
          "type": "string",
          "description": "The key that made the request."
        },
        "request_id": {
          "type": "string"
        },
        "recipients": {
          "type": "integer"
        },
        "summary": {
          "type": "object",
          "additionalProperties": true,
          "description": "What was held: recipients, template, text, media, broadcast_name, scheduled_for."
        },
        "resolved_at": {
          "type": "string",
          "format": "date-time"
        },
        "resolved_by": {
          "type": "string",
          "example": "dashboard"
        },
        "result": {
          "type": "object",
          "additionalProperties": true,
          "description": "After approval: status, accepted, failed, broadcast_code, error."
        },
        "url": {
          "type": "string"
        },
        "approve_url": {
          "type": "string"
        }
      }
    },
    "ApprovalsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "approvals": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Approval"
          }
        },
        "count": {
          "type": "integer"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ApprovalResolveResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "approval": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "approved",
                "rejected"
              ]
            },
            "resolved_by": {
              "type": "string"
            },
            "resolved_at": {
              "type": "string",
              "format": "date-time"
            },
            "result": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "send": {
          "$ref": "#/definitions/SendMessageResponse",
          "description": "Approved only: the answer the original request would have got."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ErrorResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": false
        },
        "request_id": {
          "type": "string",
          "example": "kxrkf",
          "description": "Quote this when contacting support."
        },
        "error": {
          "$ref": "#/definitions/Error"
        }
      }
    },
    "Error": {
      "type": "object",
      "required": [
        "code",
        "message",
        "how_to_fix"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "account_deactivated",
            "account_not_confirmed",
            "account_service_error",
            "account_service_unavailable",
            "api_key_expired",
            "api_key_number_mismatch",
            "api_key_old_format",
            "api_key_revoked",
            "approval_already_resolved",
            "approval_body_too_large",
            "approval_expired",
            "approval_not_found",
            "automation_not_found",
            "background_start_failed",
            "block_list_busy",
            "block_list_full",
            "block_not_found",
            "block_users_error",
            "block_users_failed",
            "booking_cancelled",
            "booking_not_enabled",
            "booking_not_found",
            "booking_slot_taken",
            "broadcast_cancelled",
            "broadcast_not_cancellable",
            "broadcast_not_found",
            "bsuid_not_supported",
            "call_permission_required",
            "caption_not_supported",
            "caption_too_long",
            "catcher_not_found",
            "client_exists",
            "client_not_editable",
            "client_not_found",
            "connection_failed",
            "connection_in_use",
            "connection_not_found",
            "contact_book_error",
            "contact_not_found",
            "conversation_not_found",
            "daily_cap_reached",
            "dataset_not_found",
            "delivery_in_progress",
            "delivery_not_found",
            "display_name_not_approved",
            "duplicate_recipients",
            "email_not_sent",
            "encryption_key_managed",
            "flow_blocked_by_integrity",
            "flow_cannot_publish",
            "flow_json_download_failed",
            "flow_json_not_found",
            "flow_json_too_large",
            "flow_name_taken",
            "flow_not_deletable",
            "flow_not_editable",
            "flow_not_found",
            "flow_not_published",
            "flow_rejected",
            "form_exists",
            "form_has_submissions",
            "form_not_found",
            "form_not_published",
            "free_form_single_recipient",
            "hold_expired",
            "hold_not_found",
            "idempotency_key_reused",
            "idempotency_request_in_progress",
            "idempotency_request_interrupted",
            "insufficient_scope",
            "internal_error",
            "invalid_addons",
            "invalid_analytics_query",
            "invalid_answers",
            "invalid_api_key",
            "invalid_auth_template",
            "invalid_authorization_header",
            "invalid_automation",
            "invalid_base64",
            "invalid_block",
            "invalid_booking",
            "invalid_bsuid",
            "invalid_call_request",
            "invalid_call_settings",
            "invalid_callback_data",
            "invalid_catalog_id",
            "invalid_client_request",
            "invalid_compare_days",
            "invalid_compliance_info",
            "invalid_components",
            "invalid_connection",
            "invalid_contact_email",
            "invalid_contacts",
            "invalid_contacts_message",
            "invalid_conversation_starters",
            "invalid_conversion_events",
            "invalid_coupon",
            "invalid_csv",
            "invalid_cursor",
            "invalid_direction",
            "invalid_display_name",
            "invalid_email",
            "invalid_estimate",
            "invalid_event_type",
            "invalid_events",
            "invalid_flow_categories",
            "invalid_flow_field",
            "invalid_flow_id",
            "invalid_flow_json",
            "invalid_flow_name",
            "invalid_form",
            "invalid_guests",
            "invalid_idempotency_key",
            "invalid_identity_key_hash",
            "invalid_insights_request",
            "invalid_interactive",
            "invalid_json",
            "invalid_keep_old_for_hours",
            "invalid_key_request",
            "invalid_library_filter",
            "invalid_limit",
            "invalid_link",
            "invalid_list",
            "invalid_location",
            "invalid_marketing_api",
            "invalid_media_id",
            "invalid_media_link",
            "invalid_media_type",
            "invalid_member",
            "invalid_months",
            "invalid_note",
            "invalid_number",
            "invalid_number_in_url",
            "invalid_numbers",
            "invalid_oba_request",
            "invalid_onboarding_request",
            "invalid_optimization_spec",
            "invalid_owner",
            "invalid_partner_settings",
            "invalid_payment",
            "invalid_phone",
            "invalid_plan",
            "invalid_poll",
            "invalid_profile",
            "invalid_public_key",
            "invalid_qr_code",
            "invalid_range",
            "invalid_reaction",
            "invalid_recipients",
            "invalid_redirect_url",
            "invalid_reply_to",
            "invalid_segment",
            "invalid_send_at",
            "invalid_series",
            "invalid_service",
            "invalid_setting",
            "invalid_settings",
            "invalid_setup",
            "invalid_slug",
            "invalid_start",
            "invalid_status",
            "invalid_submission",
            "invalid_template_category",
            "invalid_template_components",
            "invalid_template_field",
            "invalid_template_ids",
            "invalid_template_language",
            "invalid_template_name",
            "invalid_template_preview",
            "invalid_test_event",
            "invalid_text",
            "invalid_ticket_check_in",
            "invalid_ticket_code",
            "invalid_ticket_event",
            "invalid_ticket_order",
            "invalid_time",
            "invalid_to",
            "invalid_username",
            "invalid_users",
            "invalid_wait",
            "invalid_webhook_format",
            "invalid_webhook_headers",
            "invalid_webhook_secret",
            "invalid_webhook_url",
            "ip_not_allowed",
            "key_limit_reached",
            "key_limits_unavailable",
            "key_not_found",
            "link_not_found",
            "link_not_usable",
            "list_not_found",
            "marketing_disabled_on_cloud_api",
            "marketing_per_user_limit",
            "marketing_status_lookup_failed",
            "media_delete_failed",
            "media_download_error",
            "media_download_failed",
            "media_lookup_failed",
            "media_lookups_paused",
            "media_not_found",
            "media_too_large",
            "media_type_not_allowed",
            "media_upload_error",
            "media_upload_failed",
            "member_not_found",
            "message_not_found",
            "message_too_old",
            "messaging_limit_restricted",
            "missing_api_key",
            "missing_file",
            "missing_interactive",
            "missing_media",
            "missing_message_id",
            "missing_numbers",
            "missing_template_language",
            "missing_template_name",
            "missing_text",
            "missing_url",
            "monthly_cap_reached",
            "monthly_limit_reached",
            "not_in_instant_sandbox",
            "note_not_found",
            "nothing_to_change",
            "number_already_verified",
            "number_not_found",
            "number_not_live",
            "optin_not_found",
            "outside_24h_window",
            "package_not_found",
            "parameter_value_invalid",
            "partner_closed",
            "partner_service_unavailable",
            "partner_suspended",
            "payment_link_failed",
            "payment_not_found",
            "payment_provider_error",
            "payments_not_connected",
            "plan_already_active",
            "plan_not_allowed",
            "plan_not_available",
            "poll_not_found",
            "profile_photo_failed",
            "qr_code_not_found",
            "range_too_large",
            "rate_limited",
            "reaction_too_old",
            "recipient_identity_changed",
            "recipient_in_experiment",
            "recipient_is_sender",
            "recipient_not_allowed",
            "recipient_not_opted_in",
            "recipient_opted_out",
            "recipient_stopped_marketing",
            "recipient_unreachable",
            "refund_not_possible",
            "register_limit_reached",
            "request_log_unavailable",
            "request_not_found",
            "request_too_large",
            "required_parameter_missing",
            "route_not_found",
            "sandbox_key",
            "sandbox_recipient",
            "sandbox_unavailable",
            "schedule_failed",
            "segment_and_recipients",
            "segment_empty",
            "segment_exists",
            "segment_not_found",
            "send_at_in_past",
            "send_at_too_far",
            "service_not_live",
            "shop_changed",
            "shop_failed",
            "shop_invalid",
            "shop_limit",
            "shop_not_enabled",
            "shop_not_found",
            "shop_not_ready",
            "shop_not_tracked",
            "shop_order_problems",
            "shop_payment_failed",
            "shop_sku_taken",
            "slug_taken",
            "stage_not_allowed",
            "submission_not_found",
            "submit_not_enabled",
            "submit_not_ready",
            "template_already_exists",
            "template_archive_failed",
            "template_category_locked",
            "template_compare_unavailable",
            "template_delete_failed",
            "template_disabled",
            "template_format_policy",
            "template_insights_confirm_required",
            "template_insights_not_enabled",
            "template_insights_unavailable",
            "template_language_not_found",
            "template_language_required",
            "template_limit_reached",
            "template_lookup_failed",
            "template_name_reserved",
            "template_not_approved",
            "template_not_editable",
            "template_not_found",
            "template_not_marketing",
            "template_parameter_count_mismatch",
            "template_parameter_format_mismatch",
            "template_parameter_invalid",
            "template_parameters_invalid",
            "template_paused",
            "template_rejected",
            "template_sample_media_failed",
            "template_text_too_long",
            "template_unarchive_failed",
            "test_event_too_large",
            "text_too_long",
            "ticket_check_in_not_found",
            "ticket_code_not_found",
            "ticket_date_not_found",
            "ticket_event_not_found",
            "ticket_event_not_publishable",
            "ticket_limit_reached",
            "ticket_not_allowed",
            "ticket_not_found",
            "ticket_order_not_found",
            "ticket_seat_not_available",
            "ticket_type_not_found",
            "tickets_not_enabled",
            "tickets_not_on_sale",
            "tickets_sold_out",
            "to_and_recipients",
            "too_late",
            "too_many_catchers",
            "too_many_invites",
            "too_many_messages_to_recipient",
            "too_many_numbers",
            "too_many_recipients",
            "too_many_segments",
            "too_many_signups",
            "too_many_templates",
            "too_many_tests",
            "too_many_webhooks",
            "unsupported_content_type",
            "unsupported_message_type",
            "username_account_not_linked",
            "username_change_limit",
            "username_not_available",
            "username_not_eligible",
            "username_taken",
            "voice_needs_ogg_opus",
            "waitlist_not_found",
            "waitlist_not_offered",
            "waitlist_not_set_up",
            "webhook_not_found",
            "webhook_url_in_use",
            "whatsapp_account_locked",
            "whatsapp_account_restricted",
            "whatsapp_connection_problem",
            "whatsapp_error",
            "whatsapp_flow_failed",
            "whatsapp_maintenance",
            "whatsapp_number_not_registered",
            "whatsapp_parameter_error",
            "whatsapp_payment_issue",
            "whatsapp_permission_missing",
            "whatsapp_rate_limit",
            "whatsapp_unavailable"
          ],
          "description": "Stable error code, safe to use in your own logic."
        },
        "message": {
          "type": "string",
          "description": "What is wrong, in plain words."
        },
        "how_to_fix": {
          "type": "string",
          "description": "What to change to make the request work."
        },
        "documentation_url": {
          "type": "string",
          "example": "https://www.app2email.com/docs/api/errors#template_not_found",
          "description": "Where this error is explained."
        },
        "is_retriable": {
          "type": "boolean",
          "description": "true: the same request can work later without a change (limits, caps, trouble on our side or WhatsApp's, a request with the same Idempotency-Key still running)."
        },
        "retry_after_seconds": {
          "type": "integer",
          "description": "How long to wait before trying again, when known (also the Retry-After header)."
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Extra information, eg the problems found, available templates or languages."
        },
        "example_request": {
          "$ref": "#/definitions/SendTemplateRequest"
        },
        "whatsapp_error": {
          "$ref": "#/definitions/WhatsAppError"
        }
      }
    },
    "WhatsAppError": {
      "type": "object",
      "description": "WhatsApp's (Meta's) own error, when the error came from WhatsApp.",
      "properties": {
        "code": {
          "type": "integer",
          "example": 132000
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "fbtrace_id": {
          "type": "string"
        }
      }
    },
    "AccountNumber": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string",
          "example": "4976659348270"
        },
        "display_number": {
          "type": "string",
          "nullable": true,
          "example": "+49 7665 9348270"
        },
        "name": {
          "type": "string",
          "nullable": true,
          "description": "The WhatsApp display name."
        },
        "status": {
          "type": "string",
          "enum": [
            "live",
            "pending_payment",
            "not_live"
          ],
          "description": "live: LIVE with a plan that includes the API. pending_payment: no such plan yet. not_live: paused, expired or still being connected."
        },
        "service_status": {
          "type": "string",
          "nullable": true,
          "example": "LIVE"
        },
        "plan": {
          "type": "string",
          "example": "standard_5000"
        },
        "plan_label": {
          "type": "string",
          "example": "Standard 5,000"
        },
        "api_allowed": {
          "type": "boolean"
        },
        "billing_period_end": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "renewal_enabled": {
          "type": "boolean"
        }
      }
    },
    "AccountSignupRequest": {
      "type": "object",
      "required": [
        "contact_email"
      ],
      "properties": {
        "contact_email": {
          "type": "string",
          "format": "email",
          "maxLength": 254,
          "description": "The person's e-mail address. They get a link to confirm."
        },
        "business_name": {
          "type": "string",
          "maxLength": 100,
          "description": "Optional: the business the account is for."
        },
        "plan": {
          "type": "string",
          "description": "Optional: a plan id from GET /v1/account/plans the person means to choose."
        }
      }
    },
    "AccountSignupResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "signup_id": {
          "type": "string",
          "example": "su_Q7pX2mLw9Rk4Tz1b"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending_email"
          ]
        },
        "management_key": {
          "type": "string",
          "description": "An account key with every account permission. Shown once. Until the person confirms, it works only for GET /v1/account; it expires with the sign-up (48 h), and stops working when a newer create_account for the same address replaces the sign-up."
        },
        "onboarding_link": {
          "type": "string",
          "format": "uri",
          "description": "Give it to the person: it says what to do next. The confirmation itself is the e-mailed link."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "next_steps": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What to do next, in plain words."
        },
        "message": {
          "type": "string"
        },
        "instant_sandbox": {
          "$ref": "#/definitions/InstantSandbox"
        }
      }
    },
    "InstantSandbox": {
      "type": "object",
      "description": "A key that works at once on app2email's demo number, where pretend customers answer and nothing reaches WhatsApp. Left out of create_account's answer when it could not be made.",
      "properties": {
        "api_key": {
          "type": "string",
          "description": "The instant sandbox key (a2es_..., 96 characters). Shown once. Send it as Authorization: Bearer on base_url or mcp_url. It works only on the demo number."
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "description": "7 days after it was made."
        },
        "number": {
          "type": "string",
          "example": "12025550100",
          "description": "The demo number: the {number} of every call."
        },
        "base_url": {
          "type": "string",
          "format": "uri",
          "example": "https://api.app2email.com/v1/12025550100"
        },
        "mcp_url": {
          "type": "string",
          "format": "uri",
          "example": "https://api.app2email.com/mcp"
        },
        "authorization": {
          "type": "string"
        },
        "what_it_is": {
          "type": "string"
        },
        "test_contacts": {
          "type": "array",
          "description": "The pretend customers: the only numbers the sandbox writes to.",
          "items": {
            "type": "object",
            "properties": {
              "number": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "behaviour": {
                "type": "string"
              }
            }
          }
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "calls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The calls the demo number has. Any other: 403 not_in_instant_sandbox."
        },
        "try_first": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "step": {
                "type": "integer"
              },
              "call": {
                "type": "string"
              },
              "body": {
                "type": "object"
              },
              "why": {
                "type": "string"
              }
            }
          }
        },
        "not_here": {
          "type": "string"
        }
      }
    },
    "EstimateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "currency": {
          "type": "string",
          "example": "USD"
        },
        "messages_per_month": {
          "type": "integer"
        },
        "plan": {
          "type": "object",
          "nullable": true,
          "description": "The cheapest plan that covers the messages (an entry of GET /v1/account/plans). null: no listed plan is large enough.",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "messages_per_month": {
              "type": "integer"
            },
            "price_monthly": {
              "type": "number"
            },
            "price_yearly": {
              "type": "number"
            },
            "api": {
              "type": "boolean"
            },
            "email_bridge": {
              "type": "boolean"
            },
            "includes": {
              "type": "string"
            }
          }
        },
        "app2email": {
          "type": "object",
          "properties": {
            "per_month": {
              "type": "number",
              "nullable": true,
              "description": "The plan's price a month (a yearly price divided by 12)."
            },
            "per_year": {
              "type": "number",
              "nullable": true
            },
            "billing": {
              "type": "string",
              "enum": [
                "monthly",
                "yearly"
              ]
            },
            "markup_on_meta_fees": {
              "type": "number",
              "example": 0
            },
            "message": {
              "type": "string"
            }
          }
        },
        "meta": {
          "type": "object",
          "description": "Meta's own fees. Only worked out from the rates the caller gave: app2email does not bill or guess them.",
          "properties": {
            "per_month": {
              "type": "number",
              "nullable": true
            },
            "lines": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string",
                    "enum": [
                      "marketing",
                      "utility",
                      "authentication",
                      "service"
                    ]
                  },
                  "messages": {
                    "type": "integer"
                  },
                  "rate": {
                    "type": "number",
                    "nullable": true
                  },
                  "cost": {
                    "type": "number",
                    "nullable": true
                  }
                }
              }
            },
            "missing_rates": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "billed_by": {
              "type": "string"
            },
            "price_list": {
              "type": "string",
              "format": "uri"
            },
            "message": {
              "type": "string"
            }
          }
        },
        "total_per_month": {
          "type": "number",
          "nullable": true,
          "description": "The plan plus Meta's fees, when every rate was given; else null."
        },
        "assumptions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "plans": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "InstantSandboxResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "instant_sandbox": {
          "$ref": "#/definitions/InstantSandbox"
        },
        "next": {
          "type": "string"
        },
        "documentation_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "AccountStatusResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "account": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pending_email",
                "pending_whatsapp",
                "pending_payment",
                "live"
              ],
              "description": "pending_email: the person has not confirmed. pending_whatsapp: no WhatsApp number yet, or a number with a plan is not LIVE (paused, being connected). pending_payment: no number has a plan with the API. live: at least one number is live."
            },
            "email": {
              "type": "string",
              "nullable": true,
              "description": "Masked until the person confirms."
            },
            "name": {
              "type": "string",
              "nullable": true
            },
            "numbers": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/AccountNumber"
              }
            },
            "signup_id": {
              "type": "string",
              "nullable": true
            },
            "signup_expires": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            }
          }
        },
        "key": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "scopes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "next_steps": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What to do next, in plain words."
        }
      }
    },
    "AccountNumbersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "numbers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccountNumber"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "AccountNumberResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "$ref": "#/definitions/AccountNumber"
        }
      }
    },
    "AccountNumberKey": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "prefix": {
          "type": "string",
          "example": "a2e_"
        },
        "first4": {
          "type": "string"
        },
        "last4": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "ip_allow": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "last_used": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "sandbox": {
          "type": "boolean"
        },
        "daily_cap": {
          "type": "integer"
        },
        "approval_above": {
          "type": "integer"
        }
      }
    },
    "AccountNumberKeysResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "keys": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccountNumberKey"
          }
        },
        "count": {
          "type": "integer"
        },
        "default_key": {
          "type": "object",
          "description": "The number's Default key (made on the dashboard): whether there is one.",
          "properties": {
            "exists": {
              "type": "boolean"
            },
            "first4": {
              "type": "string",
              "nullable": true
            },
            "last4": {
              "type": "string",
              "nullable": true
            }
          }
        }
      }
    },
    "AccountNumberKeyRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 60,
          "default": "Agent"
        },
        "scopes": {
          "type": "string",
          "enum": [
            "full",
            "send",
            "read"
          ],
          "description": "full (default), send, read, or a list of number permissions (as on the dashboard), or [\"*\"]."
        },
        "sandbox": {
          "type": "boolean",
          "default": true,
          "description": "true (default): sends are simulated, nothing goes to WhatsApp. false: a live key."
        },
        "expires_days": {
          "type": "integer",
          "minimum": 1,
          "maximum": 365
        },
        "ip_allow": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "description": "IPs or IPv4 ranges that may use the key."
        },
        "daily_cap": {
          "type": "integer",
          "minimum": 0,
          "description": "Most messages per UTC day; 0 = no cap."
        },
        "approval_above": {
          "type": "integer",
          "minimum": 0,
          "description": "A send to more recipients waits for approval; 0 = never."
        }
      }
    },
    "AccountNumberKeyCreated": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "api_key": {
          "type": "string",
          "description": "The key. Shown once."
        },
        "key": {
          "$ref": "#/definitions/AccountNumberKey"
        },
        "number": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "AccountRevokeResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "revoked": {
          "type": "boolean"
        },
        "key_id": {
          "type": "integer"
        },
        "number": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "AccountPlan": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "standard_5000"
        },
        "type": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "messages_per_month": {
          "type": "integer"
        },
        "price_monthly": {
          "type": "number"
        },
        "price_yearly": {
          "type": "number"
        },
        "api": {
          "type": "boolean",
          "description": "The plan includes the API and MCP."
        },
        "email_bridge": {
          "type": "boolean"
        },
        "includes": {
          "type": "string"
        }
      }
    },
    "AccountPlansResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "yearly_discount": {
          "type": "number"
        },
        "plans": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccountPlan"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "AccountCheckoutRequest": {
      "type": "object",
      "required": [
        "plan"
      ],
      "properties": {
        "plan": {
          "type": "string",
          "description": "A plan id from GET /v1/account/plans."
        },
        "yearly": {
          "type": "boolean",
          "default": false
        }
      }
    },
    "AccountCheckoutResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "plan": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "messages_per_month": {
              "type": "integer"
            },
            "price": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "interval": {
              "type": "string",
              "enum": [
                "month",
                "year"
              ]
            }
          }
        },
        "checkout_url": {
          "type": "string",
          "format": "uri",
          "description": "Stripe Checkout. Give it to the person."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "test_mode": {
          "type": "boolean",
          "description": "true on app2email's test site (Stripe test mode)."
        },
        "message": {
          "type": "string"
        }
      }
    },
    "AccountUsageResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "numbers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "number": {
                "type": "string"
              },
              "plan": {
                "type": "string"
              },
              "service_status": {
                "type": "string",
                "nullable": true
              },
              "billing_period": {
                "type": "object",
                "properties": {
                  "start": {
                    "type": "string",
                    "nullable": true
                  },
                  "end": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "plan_messages": {
                "type": "object",
                "properties": {
                  "whatsapp_sent": {
                    "type": "integer"
                  },
                  "emails_sent": {
                    "type": "integer"
                  },
                  "total_sent": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  },
                  "left": {
                    "type": "integer"
                  }
                }
              },
              "messages_received_this_billing_month": {
                "type": "integer"
              }
            }
          }
        },
        "totals": {
          "type": "object",
          "properties": {
            "total_sent": {
              "type": "integer"
            },
            "whatsapp_sent": {
              "type": "integer"
            },
            "emails_sent": {
              "type": "integer"
            }
          }
        }
      }
    },
    "AccountKey": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "ak_Hc4dR8sLm2Qv9Xw1"
        },
        "name": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prefix": {
          "type": "string",
          "example": "a2e_acct_"
        },
        "first4": {
          "type": "string"
        },
        "last4": {
          "type": "string"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "created_by": {
          "type": "string",
          "enum": [
            "dashboard",
            "api",
            "create_account"
          ]
        },
        "last_used": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "management_key": {
          "type": "boolean",
          "description": "Made by create_account (an agent's sign-up)."
        }
      }
    },
    "AccountKeysResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "keys": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccountKey"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "AccountKeyRequest": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 60
        },
        "scopes": {
          "type": "string",
          "enum": [
            "full",
            "read"
          ],
          "description": "full (default), read, or a list of account permissions. Never more than the calling key has."
        },
        "expires_days": {
          "type": "integer",
          "minimum": 1,
          "maximum": 365
        }
      }
    },
    "AccountKeyCreated": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "account_key": {
          "type": "string",
          "description": "The key. Shown once."
        },
        "key": {
          "$ref": "#/definitions/AccountKey"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "PricingDataPoint": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "format": "date-time"
        },
        "end": {
          "type": "string",
          "format": "date-time"
        },
        "pricing_category": {
          "type": "string",
          "description": "MARKETING, UTILITY, AUTHENTICATION, AUTHENTICATION_INTERNATIONAL, MARKETING_LITE, SERVICE, REFERRAL_CONVERSION."
        },
        "pricing_type": {
          "type": "string",
          "description": "REGULAR, FREE_CUSTOMER_SERVICE, FREE_ENTRY_POINT."
        },
        "country": {
          "type": "string"
        },
        "tier": {
          "type": "string",
          "description": "Volume tier, eg 0:750000 (with dimensions tier)."
        },
        "phone_number": {
          "type": "string"
        },
        "volume": {
          "type": "integer"
        },
        "cost": {
          "type": "number",
          "description": "In the WhatsApp Business Account's currency. Not given when the account uses a partner's credit line."
        }
      },
      "additionalProperties": true
    },
    "PricingAnalyticsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "a1n2l"
        },
        "since": {
          "type": "string",
          "format": "date-time"
        },
        "until": {
          "type": "string",
          "format": "date-time"
        },
        "granularity": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "data_points": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PricingDataPoint"
          }
        },
        "totals": {
          "type": "object",
          "properties": {
            "volume": {
              "type": "number"
            },
            "cost": {
              "type": "number"
            }
          }
        }
      },
      "required": [
        "success",
        "request_id",
        "data_points"
      ]
    },
    "MessageDataPoint": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "format": "date-time"
        },
        "end": {
          "type": "string",
          "format": "date-time"
        },
        "sent": {
          "type": "integer"
        },
        "delivered": {
          "type": "integer"
        }
      },
      "additionalProperties": true
    },
    "MessageAnalyticsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "a1n2l"
        },
        "since": {
          "type": "string",
          "format": "date-time"
        },
        "until": {
          "type": "string",
          "format": "date-time"
        },
        "granularity": {
          "type": "string"
        },
        "data_points": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MessageDataPoint"
          }
        },
        "totals": {
          "type": "object",
          "properties": {
            "sent": {
              "type": "integer"
            },
            "delivered": {
              "type": "integer"
            }
          }
        }
      },
      "required": [
        "success",
        "request_id",
        "data_points"
      ]
    },
    "AccountActivity": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "event_type": {
          "type": "string",
          "description": "eg PHONE_NUMBER_DEREGISTERED_FROM_CLOUD_API, TWO_STEP_VERIFICATION_PIN_CHANGED, PARTNER_REMOVED, BILLING_DELETED."
        },
        "category": {
          "type": "string",
          "description": "ACCOUNT, APP, BILLING, BUSINESS_PROFILE, MESSAGE_TEMPLATE, PAYMENT_CONFIGURATION, PHONE_NUMBER, USER ..."
        },
        "actor_id": {
          "type": "string"
        },
        "actor_business_id": {
          "type": "string"
        },
        "time": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "AccountActivityResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "a1n2l"
        },
        "activities": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccountActivity"
          }
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id",
        "activities"
      ]
    },
    "ConversionsDatasetRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        }
      }
    },
    "ConversionsDatasetResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "a1n2l"
        },
        "dataset": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        }
      },
      "required": [
        "success",
        "request_id",
        "dataset"
      ]
    },
    "ConversionEvent": {
      "type": "object",
      "properties": {
        "event_name": {
          "type": "string",
          "description": "eg Purchase, LeadSubmitted, AddToCart."
        },
        "event_time": {
          "type": "integer",
          "description": "Unix seconds, within the last 7 days. Default: now."
        },
        "action_source": {
          "type": "string",
          "default": "business_messaging"
        },
        "messaging_channel": {
          "type": "string",
          "default": "whatsapp"
        },
        "user_data": {
          "type": "object",
          "properties": {
            "ctwa_clid": {
              "type": "string",
              "description": "The click id of the click-to-WhatsApp ad (referral.ctwa_clid of the contact's first message)."
            },
            "whatsapp_business_account_id": {
              "type": "string",
              "description": "Default: this number's WABA."
            }
          },
          "additionalProperties": true
        },
        "custom_data": {
          "type": "object",
          "properties": {
            "currency": {
              "type": "string"
            },
            "value": {
              "type": "number"
            }
          },
          "additionalProperties": true
        }
      },
      "required": [
        "event_name"
      ],
      "additionalProperties": true
    },
    "ConversionEventsRequest": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "minItems": 1,
          "maxItems": 1000,
          "items": {
            "$ref": "#/definitions/ConversionEvent"
          }
        },
        "test_event_code": {
          "type": "string",
          "description": "From Events Manager: the events show under Test events and are not used for ads."
        },
        "partner_agent": {
          "type": "string"
        }
      },
      "required": [
        "data"
      ]
    },
    "ConversionEventsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "a1n2l"
        },
        "dataset_id": {
          "type": "string"
        },
        "events_received": {
          "type": "integer"
        },
        "messages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "fbtrace_id": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "DatasetQualityResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "a1n2l"
        },
        "dataset_id": {
          "type": "string"
        },
        "quality": {
          "type": "object",
          "properties": {
            "web": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "event_name": {
                    "type": "string"
                  },
                  "event_match_quality": {
                    "type": "object",
                    "properties": {
                      "composite_score": {
                        "type": "number"
                      },
                      "match_key_feedback": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "identifier": {
                              "type": "string"
                            },
                            "coverage": {
                              "type": "object",
                              "properties": {
                                "percentage": {
                                  "type": "number"
                                }
                              },
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        }
                      }
                    },
                    "additionalProperties": true
                  },
                  "event_coverage": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  },
                  "dedupe_key_feedback": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    }
                  },
                  "data_freshness": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  },
                  "acr": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  }
                },
                "additionalProperties": true
              }
            }
          },
          "description": "Meta's dataset_quality answer as it came (the fields asked for).",
          "additionalProperties": true
        }
      },
      "required": [
        "success",
        "request_id",
        "dataset_id",
        "quality"
      ]
    },
    "WaitlistEntry": {
      "type": "object",
      "description": "A customer waiting for a time on a full day of a service. Also the data of the waitlist.* events.",
      "properties": {
        "id": {
          "type": "integer"
        },
        "reference": {
          "type": "string",
          "example": "WL-4HT9XC",
          "description": "The entry's code. The customer confirms a public-link entry by sending \"Join waitlist WL-XXXXXX\" on WhatsApp, and leaves with \"Leave waitlist WL-XXXXXX\"."
        },
        "status": {
          "type": "string",
          "enum": [
            "pending_confirm",
            "waiting",
            "notified",
            "booked",
            "expired",
            "removed"
          ],
          "description": "pending_confirm: joined on the public booking page, not confirmed on WhatsApp yet. waiting. notified: offered a time that opened (up to 3 offers). booked: the customer booked that service that day. expired: the day passed. removed."
        },
        "service_id": {
          "type": "string"
        },
        "service_name": {
          "type": "string"
        },
        "provider_id": {
          "type": "string",
          "description": "'' = anyone."
        },
        "provider_name": {
          "type": "string"
        },
        "date": {
          "type": "string",
          "description": "The wanted day, YYYY-MM-DD in the business time zone."
        },
        "date_label": {
          "type": "string"
        },
        "slot_id": {
          "type": "string",
          "description": "'' = any time that day; else the full group time yyyy-MM-ddTHH:mm."
        },
        "time_label": {
          "type": "string"
        },
        "contact": {
          "type": "string"
        },
        "contact_name": {
          "type": "string"
        },
        "contact_email": {
          "type": "string"
        },
        "seats": {
          "type": "integer"
        },
        "source": {
          "type": "string",
          "enum": [
            "web",
            "calendar",
            "api"
          ]
        },
        "notified_count": {
          "type": "integer"
        },
        "notified_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "appointment_id": {
          "type": "integer",
          "nullable": true,
          "description": "The booking, once booked."
        },
        "note": {
          "type": "string",
          "description": "What the last offer did, in plain words."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        },
        "day": {
          "type": "string",
          "description": "The same as date."
        },
        "slot_local": {
          "type": "string",
          "description": "The same as slot_id."
        },
        "contact_masked": {
          "type": "string",
          "description": "The contact with all but the last 4 digits hidden."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "The same as created."
        }
      }
    },
    "WaitlistRequest": {
      "type": "object",
      "required": [
        "contact",
        "service_id",
        "date"
      ],
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer's WhatsApp number with country code, digits only, or their business-scoped user id."
        },
        "name": {
          "type": "string",
          "example": "Jane"
        },
        "email": {
          "type": "string",
          "description": "Optional: the offer goes by e-mail when WhatsApp cannot be used."
        },
        "service_id": {
          "type": "string",
          "example": "haircut",
          "description": "A service with its waitlist switched on (config.services[].waitlist)."
        },
        "provider_id": {
          "type": "string",
          "description": "Optional: one staff member. Left out: anyone."
        },
        "date": {
          "type": "string",
          "example": "2026-11-20",
          "description": "The wanted day, YYYY-MM-DD in the business time zone."
        },
        "slot_id": {
          "type": "string",
          "description": "Optional: a full group time on that day, yyyy-MM-ddTHH:mm (slot_local is taken too)."
        },
        "seats": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 1,
          "description": "Places wanted on a group service."
        },
        "force": {
          "type": "boolean",
          "default": false,
          "description": "true: add even when the day still has free times."
        }
      }
    },
    "WaitlistEntryResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "entry": {
          "$ref": "#/definitions/WaitlistEntry"
        },
        "existing": {
          "type": "boolean",
          "description": "true: the customer was on that day's waitlist for the service already (this is that entry)."
        }
      }
    },
    "WaitlistListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "entries": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/WaitlistEntry"
          }
        },
        "count": {
          "type": "integer"
        },
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        },
        "timezone": {
          "type": "string"
        }
      }
    },
    "BookingService": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "haircut"
        },
        "name": {
          "type": "string",
          "example": "Haircut"
        },
        "duration_min": {
          "type": "integer",
          "example": 30
        }
      }
    },
    "Booking": {
      "type": "object",
      "description": "An appointment. The same object is the data of the booking.created, booking.cancelled, booking.rescheduled and booking.rated webhook events.",
      "properties": {
        "id": {
          "type": "integer",
          "example": 42
        },
        "reference": {
          "type": "string",
          "example": "BK-7Q3M2A",
          "description": "The short code the customer sees. GET /bookings/{id} takes it too."
        },
        "status": {
          "type": "string",
          "enum": [
            "confirmed",
            "cancelled",
            "completed",
            "no_show"
          ]
        },
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer's number (digits, country code first) or their business-scoped user id."
        },
        "contact_name": {
          "type": "string",
          "example": "John Smith"
        },
        "contact_email": {
          "type": "string",
          "example": "john@example.com"
        },
        "service": {
          "$ref": "#/definitions/BookingService"
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "timezone": {
          "type": "string",
          "example": "Australia/Sydney",
          "description": "The business time zone the slot was chosen in."
        },
        "source": {
          "type": "string",
          "enum": [
            "whatsapp_flow",
            "dashboard",
            "api",
            "web"
          ],
          "description": "Booked by the customer in WhatsApp, on the dashboard (or in the calendar app), through this API, or by the customer on the online booking page (web)."
        },
        "calendar": {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "builtin",
                "google",
                "microsoft",
                "caldav",
                "ics"
              ]
            },
            "event_id": {
              "type": "string"
            },
            "url": {
              "type": "string"
            },
            "error": {
              "type": "string",
              "description": "The calendar write failed; the booking still stands."
            }
          }
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "Every other field the customer filled in the Flow."
        },
        "notes": {
          "type": "string"
        },
        "provider": {
          "type": "object",
          "description": "The staff member, when the business has them. Left out otherwise.",
          "properties": {
            "id": {
              "type": "string",
              "example": "maria"
            },
            "name": {
              "type": "string",
              "example": "Maria"
            }
          }
        },
        "rating": {
          "type": "integer",
          "enum": [
            1,
            3,
            5
          ],
          "description": "The customer's rating from the follow-up message (5 loved it, 3 OK, 1 not great). Left out until given."
        },
        "payment_status": {
          "type": "string",
          "enum": [
            "link_sent",
            "paid",
            "waived"
          ],
          "description": "The business's own note on the payment. Left out when none."
        },
        "credits_used": {
          "type": "integer",
          "description": "Always 0 (memberships were removed on 2026-11-10); kept so existing integrations keep parsing."
        },
        "attendance_confirmed": {
          "type": "string",
          "format": "date-time",
          "description": "When the customer tapped Confirm on a reminder."
        },
        "cancelled": {
          "type": "object",
          "description": "Only when cancelled.",
          "properties": {
            "at": {
              "type": "string",
              "format": "date-time"
            },
            "by": {
              "type": "string",
              "enum": [
                "customer",
                "business",
                "api",
                "system"
              ]
            },
            "reason": {
              "type": "string"
            }
          }
        },
        "rescheduled_from_id": {
          "type": "integer",
          "description": "The appointment this one replaced."
        },
        "link_id": {
          "type": "integer",
          "nullable": true,
          "description": "The online booking link (/book/...) it was made through, for correlation. null: none."
        },
        "notes_count": {
          "type": "integer",
          "description": "How many internal notes are written on this appointment (GET /bookings/{id}/notes). Given by the calendar routes and the list; left out of webhook events."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "location": {
          "type": "object",
          "nullable": true,
          "description": "Where it takes place, as chosen (null: the service has no locations; then config.messages.location). value: the address, the number, the link; a video link made by the connected Google or Microsoft calendar appears here once made. text: how the messages show it.",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "in_person",
                "phone_we_call",
                "phone_you_call",
                "video",
                "customer_address",
                "custom"
              ]
            },
            "label": {
              "type": "string"
            },
            "value": {
              "type": "string"
            },
            "text": {
              "type": "string"
            }
          }
        },
        "addons": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "price_amount": {
                "type": "number"
              },
              "duration_min": {
                "type": "integer"
              }
            }
          },
          "description": "The add-ons booked (copied at booking time)."
        },
        "guests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              }
            }
          },
          "description": "The people who come along."
        },
        "answer_items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            }
          },
          "description": "The answers to the service's questions as label / value (the raw ones are in answers.q)."
        },
        "series": {
          "type": "object",
          "nullable": true,
          "description": "This appointment is one of a series (null: not).",
          "properties": {
            "id": {
              "type": "string",
              "example": "SR-7Q3M2A"
            },
            "index": {
              "type": "integer"
            },
            "count": {
              "type": "integer"
            },
            "freq": {
              "type": "string",
              "enum": [
                "weekly",
                "biweekly",
                "every4weeks",
                "monthly"
              ]
            }
          }
        },
        "seats": {
          "type": "integer",
          "description": "The places this booking takes on a group time (1 + guests); 1 otherwise."
        }
      }
    },
    "BookingsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "bookings": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Booking"
          }
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        },
        "count": {
          "type": "integer"
        },
        "order": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether Book-and-Pay is switched on for the number."
        },
        "timezone": {
          "type": "string"
        }
      }
    },
    "BookingResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "booking": {
          "$ref": "#/definitions/Booking"
        },
        "note": {
          "type": "string"
        },
        "series": {
          "$ref": "#/definitions/BookingSeriesAnswer"
        }
      }
    },
    "BookingCreateRequest": {
      "type": "object",
      "required": [
        "contact",
        "service_id",
        "start",
        "name"
      ],
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer's WhatsApp number with country code, digits only, or their business-scoped user id."
        },
        "service_id": {
          "type": "string",
          "example": "haircut",
          "description": "One of config.services[].id (GET /settings/booking)."
        },
        "start": {
          "type": "string",
          "example": "2026-11-10T09:00",
          "description": "A free slot's id from GET /bookings/availability: local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "name": {
          "type": "string",
          "maxLength": 200,
          "example": "John Smith"
        },
        "email": {
          "type": "string",
          "format": "email",
          "example": "john@example.com"
        },
        "notes": {
          "type": "string",
          "maxLength": 2000,
          "description": "Notes for the business."
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "The staff member (config.providers[].id). Left out: the first free one."
        },
        "notify": {
          "type": "boolean",
          "default": true,
          "description": "Send the customer the confirmation on WhatsApp (a text inside their 24 hour window, else the booking confirmation template)."
        },
        "answers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Optional extra fields kept with the booking."
        },
        "hold": {
          "type": "string",
          "example": "BK-4HT9XC",
          "description": "The reference of a held time (POST /bookings/holds): the booking is made from that hold, takes its reference and frees it. `contact` and `name` from this body win over the hold's; service and time come from the hold."
        },
        "answers_q": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "hair_length": "Long",
            "allergies": [
              "Latex"
            ],
            "terms": true
          },
          "description": "The answers to the service's questions (config.services[].questions), by question id: text, a list for a multi-choice question, true for a tick box. Required questions must be answered (400 `invalid_answers`)."
        },
        "location_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3,
          "description": "Which of the service's locations (config.services[].locations, 0-based). Left out: the first."
        },
        "location_value": {
          "type": "string",
          "maxLength": 300,
          "description": "The customer's address, for an at-your-address location (5 to 300 characters)."
        },
        "addon_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "deep"
          ],
          "description": "The service's add-ons (config.services[].addons ids): each adds its price and minutes (400 `invalid_addons` for one the service does not offer)."
        },
        "guests": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 60
              },
              "phone": {
                "type": "string",
                "description": "Digits, or empty."
              }
            }
          },
          "description": "People who come along, up to config.services[].guests_max; on a group service each takes a place (400 `invalid_guests`)."
        },
        "utm": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "maxLength": 100
            },
            "medium": {
              "type": "string",
              "maxLength": 100
            },
            "campaign": {
              "type": "string",
              "maxLength": 100
            },
            "term": {
              "type": "string",
              "maxLength": 100
            },
            "content": {
              "type": "string",
              "maxLength": 100
            }
          },
          "description": "Kept with the booking (answers.utm)."
        },
        "series": {
          "type": "object",
          "description": "Book a series: one appointment per occurrence (each its own reference and reminders; monthly = the same day of the month, a month without it is skipped). Every date is checked; the ones that are not free are skipped and listed in series.skipped of the answer. The customer gets one confirmation. Not with hold.",
          "required": [
            "freq",
            "count"
          ],
          "properties": {
            "freq": {
              "type": "string",
              "enum": [
                "weekly",
                "biweekly",
                "every4weeks",
                "monthly"
              ]
            },
            "count": {
              "type": "integer",
              "minimum": 2,
              "maximum": 52
            }
          }
        }
      }
    },
    "BookingSeriesAnswer": {
      "type": "object",
      "description": "A series that was booked (POST /bookings with series).",
      "properties": {
        "id": {
          "type": "string",
          "example": "SR-7Q3M2A"
        },
        "booked": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Booking"
          }
        },
        "skipped": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "index": {
                "type": "integer"
              },
              "start_local": {
                "type": "string"
              },
              "date_label": {
                "type": "string"
              },
              "reason": {
                "type": "string",
                "example": "Thu 3 Dec 10:00 is taken - not booked"
              }
            }
          }
        }
      }
    },
    "BookingCancelRequest": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "maxLength": 500,
          "example": "customer asked by phone"
        },
        "notify": {
          "type": "boolean",
          "default": true,
          "description": "Tell the customer on WhatsApp (a text inside their 24 hour window, else the cancellation template)."
        },
        "scope": {
          "type": "string",
          "enum": [
            "one",
            "following"
          ],
          "default": "one",
          "description": "following: this appointment and the later ones of its series (the customer gets one message); the answer adds series { id, cancelled, skipped }."
        }
      }
    },
    "BookingStatusRequest": {
      "type": "object",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "completed",
            "no_show",
            "confirmed"
          ],
          "description": "completed: the customer came. no_show: they did not. confirmed: undo one of those (within 7 days of the end)."
        }
      }
    },
    "AvailabilitySlot": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "2026-11-10T09:00",
          "description": "Local time in the business time zone: what POST /bookings takes as start."
        },
        "title": {
          "type": "string",
          "example": "9:00 AM"
        },
        "start": {
          "type": "string",
          "format": "date-time"
        },
        "end": {
          "type": "string",
          "format": "date-time"
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The staff members free at this time, when the business has them."
        },
        "start_utc": {
          "type": "string",
          "format": "date-time",
          "description": "The same instant as start (for showing it in another time zone)."
        },
        "seats_left": {
          "type": "integer",
          "description": "A group service: the places left at this time. 0 = a full time, listed only when the service has a waitlist."
        }
      }
    },
    "AvailabilityDay": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "example": "2026-11-10"
        },
        "slots": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AvailabilitySlot"
          },
          "description": "Empty on a closed or full day."
        },
        "waitlist": {
          "type": "boolean",
          "description": "true: the day has no free time and the service has a waitlist (left out otherwise)."
        }
      }
    },
    "AvailabilityResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "days": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AvailabilityDay"
          }
        },
        "timezone": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        }
      }
    },
    "BookingSettings": {
      "type": "object",
      "description": "The booking configuration, by section. trigger: the words that send the Flow, its intro text and button; schedule: timezone, opening hours per weekday (hours.mon ... [[\"09:00\", \"17:00\"]]), slot_interval_min, buffers, min_notice_min, max_advance_days, max_per_slot, max_per_day (the most appointments on one day, per staff member when there is staff; 0 = no limit), cancel_notice_min (a customer may cancel or move only until this many minutes before the start; 0 = any time), overrides (closed days); services: id, name, duration_min, description, price, enabled, prep_text, aftercare_text, retail_links, payment_link, deposit_text; details: ask_email, ask_notes; messages: the texts the customer gets (placeholders {service} {date} {time} {duration} {business} {location} {reference} {name} {phone} {notes} {end_time} {provider} {prep} {booking_link}), web: see the web property, reminders, followup, rebook, notify_email; calendar: provider (builtin | google | microsoft | caldav | ics | calcom | calendly | acuity | square | msbookings | simplybook | setmore | zohobookings), write_calendar_id, busy_calendar_ids, event_title, event_description; providers: the staff members. GET /settings/booking shows every key with its value.",
      "additionalProperties": true,
      "properties": {
        "trigger": {
          "type": "object",
          "additionalProperties": true,
          "description": "The words that start a booking, and the message with the button. `other_words_limit` (default 10, 0 to 100): a trigger word counts only when the message has fewer than this many other words, so a long message never starts a Flow; 0 = a message of any length.",
          "example": {
            "keywords": [
              "book",
              "appointment"
            ],
            "other_words_limit": 10,
            "intro_text": "Tap the button below to choose a time that suits you.",
            "cta": "Book now"
          }
        },
        "schedule": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "timezone": "Australia/Sydney",
            "slot_interval_min": 30,
            "min_notice_min": 120,
            "max_advance_days": 30
          }
        },
        "services": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "example": [
            {
              "id": "haircut",
              "name": "Haircut",
              "duration_min": 30,
              "price": "$40",
              "enabled": true
            }
          ]
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "ask_email": true,
            "ask_notes": true
          }
        },
        "messages": {
          "type": "object",
          "additionalProperties": true
        },
        "calendar": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "provider": "builtin"
          }
        },
        "web": {
          "type": "object",
          "additionalProperties": true,
          "description": "The online booking page: enabled, slug (the public address /book/<slug>; unique, 5 to 40 characters of a-z 0-9 and - for a new or changed address), headline, intro, trigger_mode (flow | link | both), link_button, link_text, link_valid_days (1..60), hold_minutes (5..30), confirm_text (must contain {reference}), allow_manage.",
          "example": {
            "enabled": true,
            "slug": "sample-salon",
            "trigger_mode": "both",
            "link_valid_days": 7,
            "hold_minutes": 10,
            "allow_manage": true
          }
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "BookingFlow": {
      "type": "object",
      "description": "A Flow of the number's Book-and-Pay section: the booking form (kind booking) or another form (kind form).",
      "properties": {
        "key": {
          "type": "string",
          "example": "booking",
          "description": "The Flow's key: what POST /flows/{key}/send takes."
        },
        "name": {
          "type": "string",
          "example": "Appointment booking"
        },
        "kind": {
          "type": "string",
          "enum": [
            "booking",
            "form"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "is_default": {
          "type": "boolean",
          "description": "The Flow the generic trigger words send."
        },
        "trigger_keywords": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Words that send this Flow."
        },
        "id": {
          "type": "string",
          "description": "Meta's id of the Flow, once uploaded."
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "draft",
            "published",
            "deprecated",
            "blocked",
            "throttled",
            "error"
          ],
          "description": "Meta's status. Only a published Flow can be sent."
        },
        "can_send": {
          "type": "boolean",
          "description": "enabled and published."
        },
        "health": {
          "type": "string",
          "description": "Meta's health word: AVAILABLE, LIMITED, BLOCKED, or empty."
        },
        "validation": {
          "type": "string",
          "description": "Meta's validation problems in words, when there are any."
        },
        "last_error": {
          "type": "string"
        },
        "last_published_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "BookingSettingsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean",
          "description": "Book-and-Pay is switched on: the trigger words send the Flow."
        },
        "configured": {
          "type": "boolean",
          "description": "false: the number has never been set up (the config shown is the default)."
        },
        "config": {
          "$ref": "#/definitions/BookingSettings"
        },
        "flow": {
          "$ref": "#/definitions/BookingFlow",
          "description": "The default Flow (the booking form)."
        },
        "flows": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BookingFlow"
          }
        },
        "key_status": {
          "type": "string",
          "enum": [
            "",
            "uploaded",
            "valid",
            "mismatch",
            "error"
          ],
          "description": "The Flow encryption key at Meta (publishing needs valid)."
        },
        "timezone": {
          "type": "string",
          "example": "Australia/Sydney"
        },
        "validation": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Problems in the stored settings, if any (a saved config is always valid; the default one is empty here)."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "BookingSettingsUpdateRequest": {
      "type": "object",
      "description": "Give enabled, config, or both. A section object in config is merged key by key into the stored section (keys left out stay); a list (services, providers, schedule.overrides) or a single value replaces what is stored. The whole result is checked before anything is saved.",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "config": {
          "$ref": "#/definitions/BookingSettings"
        }
      }
    },
    "BookingReport": {
      "type": "object",
      "properties": {
        "days": {
          "type": "integer",
          "enum": [
            7,
            30,
            90
          ]
        },
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        },
        "bookings": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer"
            },
            "by_source": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              },
              "description": "whatsapp_flow, dashboard, api."
            }
          }
        },
        "completed": {
          "type": "integer"
        },
        "cancelled": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer"
            },
            "by": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              },
              "description": "customer, business, api, system."
            }
          }
        },
        "no_shows": {
          "type": "integer"
        },
        "no_show_rate": {
          "type": "number",
          "description": "no_shows / (completed + no_shows)."
        },
        "csat": {
          "type": "object",
          "properties": {
            "average": {
              "type": "number",
              "description": "Of the ratings 1, 3, 5. Left null without ratings."
            },
            "responses": {
              "type": "integer"
            }
          }
        },
        "reminders_sent": {
          "type": "integer"
        },
        "sessions": {
          "type": "object",
          "description": "Flow sessions started and completed (the conversion of the form).",
          "properties": {
            "started": {
              "type": "integer"
            },
            "completed": {
              "type": "integer"
            },
            "conversion": {
              "type": "number"
            }
          }
        },
        "top_services": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "per_provider": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "nudges": {
          "type": "object",
          "properties": {
            "rebook": {
              "type": "integer"
            }
          }
        },
        "error": {
          "type": "string",
          "description": "Only when the numbers could not be computed."
        },
        "range": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string"
            },
            "to": {
              "type": "string"
            },
            "days": {
              "type": "integer"
            },
            "timezone": {
              "type": "string"
            }
          },
          "description": "The days of the report (business time zone, both included)."
        },
        "filters": {
          "type": "object",
          "properties": {
            "service": {
              "type": "string"
            },
            "provider": {
              "type": "string"
            }
          }
        },
        "totals": {
          "type": "object",
          "description": "Over the appointments whose START is in the range.",
          "properties": {
            "booked": {
              "type": "integer"
            },
            "confirmed_upcoming": {
              "type": "integer"
            },
            "completed": {
              "type": "integer"
            },
            "cancelled": {
              "type": "integer"
            },
            "cancelled_by_customer": {
              "type": "integer"
            },
            "no_show": {
              "type": "integer"
            },
            "new_customers": {
              "type": "integer"
            },
            "returning_customers": {
              "type": "integer"
            },
            "revenue_minor": {
              "type": "integer"
            },
            "refunded_minor": {
              "type": "integer"
            },
            "no_show_rate": {
              "type": "number"
            },
            "cancel_rate": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "avg_lead_days": {
              "type": "number",
              "nullable": true
            },
            "online_share": {
              "type": "number",
              "description": "The share booked by the customers themselves (the WhatsApp Flow and the online page)."
            }
          }
        },
        "by_day": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              },
              "cancelled": {
                "type": "integer"
              },
              "no_show": {
                "type": "integer"
              },
              "revenue_minor": {
                "type": "integer"
              }
            }
          }
        },
        "by_weekday_hour": {
          "type": "array",
          "description": "Not cancelled appointments per start weekday (0 = Monday) and hour; only the cells that have some.",
          "items": {
            "type": "object",
            "properties": {
              "weekday": {
                "type": "integer"
              },
              "hour": {
                "type": "integer"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "by_service": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              },
              "cancelled": {
                "type": "integer"
              },
              "no_show": {
                "type": "integer"
              },
              "revenue_minor": {
                "type": "integer"
              }
            }
          }
        },
        "by_provider": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              },
              "cancelled": {
                "type": "integer"
              },
              "no_show": {
                "type": "integer"
              },
              "revenue_minor": {
                "type": "integer"
              }
            }
          }
        },
        "by_source": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              }
            }
          }
        },
        "waitlist": {
          "type": "object",
          "nullable": true,
          "properties": {
            "joined": {
              "type": "integer"
            },
            "notified": {
              "type": "integer"
            },
            "booked": {
              "type": "integer"
            }
          },
          "description": "The waitlist entries of the days of the range. null while the waitlist is not available."
        },
        "truncated": {
          "type": "boolean",
          "description": "true when the range has over 50000 appointments (only the first 50000 are counted)."
        }
      }
    },
    "BookingReportResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "days": {
          "type": "integer",
          "enum": [
            7,
            30,
            90
          ]
        },
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        },
        "bookings": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer"
            },
            "by_source": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              },
              "description": "whatsapp_flow, dashboard, api."
            }
          }
        },
        "completed": {
          "type": "integer"
        },
        "cancelled": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer"
            },
            "by": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              },
              "description": "customer, business, api, system."
            }
          }
        },
        "no_shows": {
          "type": "integer"
        },
        "no_show_rate": {
          "type": "number",
          "description": "no_shows / (completed + no_shows)."
        },
        "csat": {
          "type": "object",
          "properties": {
            "average": {
              "type": "number",
              "description": "Of the ratings 1, 3, 5. Left null without ratings."
            },
            "responses": {
              "type": "integer"
            }
          }
        },
        "reminders_sent": {
          "type": "integer"
        },
        "sessions": {
          "type": "object",
          "description": "Flow sessions started and completed (the conversion of the form).",
          "properties": {
            "started": {
              "type": "integer"
            },
            "completed": {
              "type": "integer"
            },
            "conversion": {
              "type": "number"
            }
          }
        },
        "top_services": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "per_provider": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "nudges": {
          "type": "object",
          "properties": {
            "rebook": {
              "type": "integer"
            }
          }
        },
        "error": {
          "type": "string",
          "description": "Only when the numbers could not be computed."
        },
        "range": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string"
            },
            "to": {
              "type": "string"
            },
            "days": {
              "type": "integer"
            },
            "timezone": {
              "type": "string"
            }
          },
          "description": "The days of the report (business time zone, both included)."
        },
        "filters": {
          "type": "object",
          "properties": {
            "service": {
              "type": "string"
            },
            "provider": {
              "type": "string"
            }
          }
        },
        "totals": {
          "type": "object",
          "description": "Over the appointments whose START is in the range.",
          "properties": {
            "booked": {
              "type": "integer"
            },
            "confirmed_upcoming": {
              "type": "integer"
            },
            "completed": {
              "type": "integer"
            },
            "cancelled": {
              "type": "integer"
            },
            "cancelled_by_customer": {
              "type": "integer"
            },
            "no_show": {
              "type": "integer"
            },
            "new_customers": {
              "type": "integer"
            },
            "returning_customers": {
              "type": "integer"
            },
            "revenue_minor": {
              "type": "integer"
            },
            "refunded_minor": {
              "type": "integer"
            },
            "no_show_rate": {
              "type": "number"
            },
            "cancel_rate": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "avg_lead_days": {
              "type": "number",
              "nullable": true
            },
            "online_share": {
              "type": "number",
              "description": "The share booked by the customers themselves (the WhatsApp Flow and the online page)."
            }
          }
        },
        "by_day": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              },
              "cancelled": {
                "type": "integer"
              },
              "no_show": {
                "type": "integer"
              },
              "revenue_minor": {
                "type": "integer"
              }
            }
          }
        },
        "by_weekday_hour": {
          "type": "array",
          "description": "Not cancelled appointments per start weekday (0 = Monday) and hour; only the cells that have some.",
          "items": {
            "type": "object",
            "properties": {
              "weekday": {
                "type": "integer"
              },
              "hour": {
                "type": "integer"
              },
              "count": {
                "type": "integer"
              }
            }
          }
        },
        "by_service": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              },
              "cancelled": {
                "type": "integer"
              },
              "no_show": {
                "type": "integer"
              },
              "revenue_minor": {
                "type": "integer"
              }
            }
          }
        },
        "by_provider": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              },
              "cancelled": {
                "type": "integer"
              },
              "no_show": {
                "type": "integer"
              },
              "revenue_minor": {
                "type": "integer"
              }
            }
          }
        },
        "by_source": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "booked": {
                "type": "integer"
              }
            }
          }
        },
        "waitlist": {
          "type": "object",
          "nullable": true,
          "properties": {
            "joined": {
              "type": "integer"
            },
            "notified": {
              "type": "integer"
            },
            "booked": {
              "type": "integer"
            }
          },
          "description": "The waitlist entries of the days of the range. null while the waitlist is not available."
        },
        "truncated": {
          "type": "boolean",
          "description": "true when the range has over 50000 appointments (only the first 50000 are counted)."
        }
      }
    },
    "FlowSendRequest": {
      "type": "object",
      "required": [
        "contact"
      ],
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The contact's WhatsApp number with country code, digits only, or their business-scoped user id. They must have written to the number in the last 24 hours."
        },
        "purpose": {
          "type": "string",
          "enum": [
            "book",
            "reschedule"
          ],
          "default": "book",
          "description": "reschedule: move the contact's next appointment (a booking Flow only)."
        }
      }
    },
    "FlowSendResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "sent": {
          "type": "boolean"
        },
        "message_id": {
          "type": "string",
          "description": "WhatsApp message id of the Flow message."
        },
        "session_id": {
          "type": "integer",
          "description": "The Flow session: booking.created / flow.completed name it."
        },
        "flow": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "kind": {
              "type": "string"
            }
          }
        },
        "contact": {
          "type": "string"
        },
        "purpose": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "Block": {
      "type": "object",
      "description": "Time that cannot be booked: time off, a break, a closed afternoon. Also the data of the calendar.block.created and calendar.block.deleted events.",
      "properties": {
        "id": {
          "type": "integer",
          "example": 3
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "The staff member it is for. Empty: the whole business."
        },
        "title": {
          "type": "string",
          "example": "Lunch",
          "description": "Up to 80 characters."
        },
        "notes": {
          "type": "string",
          "description": "Up to 500 characters."
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "start_local": {
          "type": "string",
          "example": "2026-11-14T12:00",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "end_local": {
          "type": "string",
          "example": "2026-11-14T13:00",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "source": {
          "type": "string",
          "enum": [
            "calendar",
            "api"
          ],
          "description": "Made in the calendar app, or through this API."
        },
        "created_by": {
          "type": "string",
          "example": "API key Planner",
          "description": "The e-mail of the person, or API key <name>."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "BlockCreateRequest": {
      "type": "object",
      "description": "Give start and end, or date for one whole day.",
      "properties": {
        "start": {
          "type": "string",
          "example": "2026-11-14T12:00",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm. Or ISO 8601 with an offset (2026-11-14T12:00:00+11:00)."
        },
        "end": {
          "type": "string",
          "example": "2026-11-14T13:00",
          "description": "Same format as start. After start, at most 31 days later."
        },
        "date": {
          "type": "string",
          "example": "2026-11-14",
          "description": "Instead of start and end: one whole day (YYYY-MM-DD, business time zone)."
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "A staff member (GET /bookings/staff). Left out: the whole business."
        },
        "title": {
          "type": "string",
          "maxLength": 80,
          "example": "Lunch"
        },
        "notes": {
          "type": "string",
          "maxLength": 500
        }
      }
    },
    "BlockUpdateRequest": {
      "type": "object",
      "description": "Any of these; what is left out stays. provider_id \"\" makes it a whole-business block.",
      "properties": {
        "start": {
          "type": "string"
        },
        "end": {
          "type": "string"
        },
        "date": {
          "type": "string",
          "description": "One whole day: sets start and end."
        },
        "provider_id": {
          "type": "string"
        },
        "title": {
          "type": "string",
          "maxLength": 80
        },
        "notes": {
          "type": "string",
          "maxLength": 500
        }
      }
    },
    "BlockResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "block": {
          "$ref": "#/definitions/Block"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "BlockDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "boolean"
        },
        "block": {
          "$ref": "#/definitions/Block"
        }
      }
    },
    "BlocksResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "blocks": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Block"
          }
        },
        "count": {
          "type": "integer"
        },
        "from": {
          "type": "string",
          "example": "2026-11-10"
        },
        "to": {
          "type": "string",
          "example": "2026-12-10"
        },
        "timezone": {
          "type": "string"
        }
      }
    },
    "Note": {
      "type": "object",
      "description": "An internal note about a customer, optionally written on one appointment. Never shown to the customer. Also the data of the booking.note.created event (plus booking and timestamp).",
      "properties": {
        "id": {
          "type": "integer",
          "example": 7
        },
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer."
        },
        "appointment_id": {
          "type": "integer",
          "nullable": true,
          "description": "The appointment it was written on. null: a note on the customer alone."
        },
        "booking_reference": {
          "type": "string",
          "nullable": true,
          "example": "BK-7Q3M2A"
        },
        "body": {
          "type": "string",
          "description": "Up to 4000 characters."
        },
        "author": {
          "type": "string",
          "example": "API key Planner",
          "description": "A person's name or e-mail, or API key <name>."
        },
        "author_kind": {
          "type": "string",
          "enum": [
            "user",
            "api",
            "agent",
            "system"
          ]
        },
        "pinned": {
          "type": "boolean"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        },
        "on_this_booking": {
          "type": "boolean",
          "description": "Only in GET /bookings/{id}/notes: written on that appointment (false: another note of the same customer)."
        }
      }
    },
    "NoteCreateRequest": {
      "type": "object",
      "required": [
        "body"
      ],
      "properties": {
        "body": {
          "type": "string",
          "maxLength": 4000,
          "example": "Prefers the window seat."
        },
        "pinned": {
          "type": "boolean",
          "default": false
        },
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "POST /bookings/notes only: the customer (number with country code, or business-scoped user id). Left out when booking_id is given."
        },
        "booking_id": {
          "type": "string",
          "example": "BK-7Q3M2A",
          "description": "POST /bookings/notes only: the appointment (id or reference) the note is written on; the customer is taken from it."
        }
      }
    },
    "NoteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "note": {
          "$ref": "#/definitions/Note"
        }
      }
    },
    "NotesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "notes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Note"
          },
          "description": "Pinned first, then newest."
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        },
        "contact": {
          "type": "string"
        },
        "booking": {
          "type": "object",
          "description": "GET /bookings/{id}/notes only.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "reference": {
              "type": "string"
            }
          }
        }
      }
    },
    "NoteDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "boolean"
        },
        "id": {
          "type": "integer"
        }
      }
    },
    "BookingLink": {
      "type": "object",
      "description": "A link that opens the online booking page. Send the url to the customer.",
      "properties": {
        "id": {
          "type": "integer"
        },
        "code": {
          "type": "string",
          "example": "k3XbQ9rTzP2m"
        },
        "url": {
          "type": "string",
          "example": "https://www.app2email.com/book/k3XbQ9rTzP2m"
        },
        "kind": {
          "type": "string",
          "enum": [
            "personal",
            "public",
            "feed"
          ],
          "description": "This API makes and lists personal links."
        },
        "contact": {
          "type": "string",
          "nullable": true,
          "description": "Who the link is for. null: a one-off link the customer confirms on WhatsApp."
        },
        "contact_name": {
          "type": "string",
          "nullable": true
        },
        "service_id": {
          "type": "string",
          "nullable": true
        },
        "provider_id": {
          "type": "string",
          "nullable": true
        },
        "purpose": {
          "type": "string",
          "enum": [
            "book",
            "reschedule",
            "manage"
          ]
        },
        "booking_id": {
          "type": "integer",
          "nullable": true,
          "description": "The appointment of a reschedule / manage link."
        },
        "single_use": {
          "type": "boolean"
        },
        "max_uses": {
          "type": "integer",
          "description": "0 = no limit."
        },
        "uses": {
          "type": "integer"
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "revoked": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "source": {
          "type": "string",
          "example": "api"
        },
        "created_by": {
          "type": "string",
          "example": "API key Planner"
        },
        "open_count": {
          "type": "integer"
        },
        "last_opened": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "state": {
          "type": "string",
          "enum": [
            "ok",
            "not_found",
            "expired",
            "revoked",
            "used_up",
            "off"
          ],
          "description": "ok: it opens. off: the online booking page is switched off."
        }
      }
    },
    "BookingLinkRequest": {
      "type": "object",
      "description": "Without contact: a one-off link; the customer confirms the booking on WhatsApp. purpose reschedule and manage need contact or booking_id.",
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer's WhatsApp number with country code, digits only, or their business-scoped user id."
        },
        "name": {
          "type": "string",
          "example": "John"
        },
        "service_id": {
          "type": "string",
          "example": "haircut",
          "description": "Preselect a service."
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "Preselect a staff member."
        },
        "purpose": {
          "type": "string",
          "enum": [
            "book",
            "reschedule",
            "manage"
          ],
          "default": "book"
        },
        "booking_id": {
          "type": "string",
          "example": "BK-7Q3M2A",
          "description": "The appointment (id or reference) of a reschedule / manage link."
        },
        "single_use": {
          "type": "boolean",
          "default": false,
          "description": "The link stops working after one booking."
        },
        "expires_in_hours": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1440,
          "description": "Default: the business's setting (7 days)."
        }
      }
    },
    "BookingLinkResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "link": {
          "$ref": "#/definitions/BookingLink"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "BookingLinksResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "links": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BookingLink"
          },
          "description": "Newest first."
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        }
      }
    },
    "Hold": {
      "type": "object",
      "description": "A time kept for a few minutes so no one else can book it.",
      "properties": {
        "reference": {
          "type": "string",
          "example": "BK-4HT9XC",
          "description": "Becomes the booking's reference when the hold is booked."
        },
        "status": {
          "type": "string",
          "enum": [
            "held",
            "booked",
            "expired",
            "released"
          ]
        },
        "service_id": {
          "type": "string"
        },
        "provider_id": {
          "type": "string",
          "nullable": true,
          "description": "The staff member the time is kept with."
        },
        "contact": {
          "type": "string",
          "nullable": true
        },
        "name": {
          "type": "string",
          "nullable": true
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "start_local": {
          "type": "string",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "end_local": {
          "type": "string",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "description": "When the time is freed."
        },
        "source": {
          "type": "string",
          "enum": [
            "web",
            "api"
          ]
        }
      }
    },
    "HoldRequest": {
      "type": "object",
      "required": [
        "service_id",
        "start"
      ],
      "properties": {
        "service_id": {
          "type": "string",
          "example": "haircut"
        },
        "start": {
          "type": "string",
          "example": "2026-11-10T09:00",
          "description": "A free slot of GET /bookings/availability or /bookings/next: Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "Left out (or \"any\"): the first free staff member who does the service."
        },
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer, when known."
        },
        "name": {
          "type": "string",
          "example": "John"
        },
        "minutes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 30,
          "default": 10,
          "description": "How long to keep the time."
        },
        "answers_q": {
          "type": "object",
          "additionalProperties": true,
          "description": "The answers to the service's questions, by question id (see POST /bookings)."
        },
        "location_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3,
          "description": "Which of the service's locations (0-based). Left out: the first."
        },
        "location_value": {
          "type": "string",
          "maxLength": 300,
          "description": "The customer's address, for an at-your-address location."
        },
        "addon_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The service's add-ons: the time is held as long as they make it."
        },
        "guests": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 60
              },
              "phone": {
                "type": "string"
              }
            }
          },
          "description": "People who come along; on a group service each takes a place."
        },
        "utm": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "{ source, medium, campaign, term, content }, kept with the booking."
        }
      }
    },
    "HoldResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "hold": {
          "$ref": "#/definitions/Hold"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "HoldReleaseResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "released": {
          "type": "boolean"
        },
        "hold": {
          "$ref": "#/definitions/Hold"
        }
      }
    },
    "CalendarEvent": {
      "type": "object",
      "description": "One entry of the calendar, told apart by kind. booking: an appointment (the Booking fields plus start_local, end_local, service_id, service_name, duration_min, provider_id, provider_name, contact, contact_name, contact_email, conversation_id, attendance_confirmed, notes_count, calendar_error, link_id). block: a Block. busy: time busy in the connected calendar (our own appointments left out). hold: a held time.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "booking",
            "block",
            "busy",
            "hold"
          ]
        },
        "id": {
          "type": "integer",
          "description": "kind booking and block."
        },
        "reference": {
          "type": "string",
          "description": "kind booking and hold."
        },
        "status": {
          "type": "string",
          "enum": [
            "confirmed",
            "cancelled",
            "completed",
            "no_show"
          ],
          "description": "kind booking."
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "description": "UTC."
        },
        "start_local": {
          "type": "string",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "end_local": {
          "type": "string",
          "description": "Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "provider_id": {
          "type": "string"
        },
        "title": {
          "type": "string",
          "description": "kind block and busy."
        },
        "service_id": {
          "type": "string"
        },
        "service_name": {
          "type": "string"
        },
        "contact": {
          "type": "string"
        },
        "contact_name": {
          "type": "string"
        },
        "notes_count": {
          "type": "integer"
        }
      },
      "additionalProperties": true
    },
    "CalendarFeed": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "timezone": {
          "type": "string",
          "example": "Australia/Sydney"
        },
        "from": {
          "type": "string",
          "example": "2026-11-10"
        },
        "to": {
          "type": "string",
          "example": "2026-11-16"
        },
        "now_local": {
          "type": "string",
          "example": "2026-11-11T10:42"
        },
        "enabled": {
          "type": "boolean",
          "description": "Book-and-Pay is switched on."
        },
        "web": {
          "type": "object",
          "description": "The online booking page.",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "slug": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "description": "Left out while the page is off."
            }
          }
        },
        "hours": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "description": "The business's open windows per day, overrides applied: {\"2026-11-10\": [[\"09:00\", \"17:00\"]]}. [] = closed."
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "The staff: id, name, enabled, services, hours per day. Empty when the number has no staff."
        },
        "services": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "id, name, duration_min, price, description, enabled."
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CalendarEvent"
          }
        }
      }
    },
    "BookableService": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "haircut"
        },
        "name": {
          "type": "string",
          "example": "Haircut"
        },
        "duration_min": {
          "type": "integer",
          "example": 30
        },
        "price": {
          "type": "string",
          "nullable": true,
          "example": "$40"
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "staff": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The staff members who do it (ids). Empty when the number has no staff."
        }
      }
    },
    "BookableServicesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "services": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BookableService"
          }
        },
        "timezone": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        }
      }
    },
    "StaffMember": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "maria"
        },
        "name": {
          "type": "string",
          "example": "Maria"
        },
        "services": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The services she does (ids)."
        }
      }
    },
    "StaffResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "staff": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/StaffMember"
          }
        },
        "timezone": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        }
      }
    },
    "NextSlot": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "2026-11-10T09:00",
          "description": "Local time: what POST /bookings, /bookings/holds and /bookings/{id}/reschedule take as start."
        },
        "date": {
          "type": "string",
          "example": "2026-11-10"
        },
        "title": {
          "type": "string",
          "example": "9:00 AM"
        },
        "start": {
          "type": "string",
          "format": "date-time"
        },
        "end": {
          "type": "string",
          "format": "date-time"
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The staff members free at this time, when the business has them."
        }
      }
    },
    "NextSlotsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "slots": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/NextSlot"
          }
        },
        "count": {
          "type": "integer"
        },
        "timezone": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        },
        "note": {
          "type": "string",
          "description": "Only when fewer free times than asked for exist in the next 60 days."
        }
      }
    },
    "BookingPatchRequest": {
      "type": "object",
      "description": "Any of these; what is left out stays. The time is changed with POST /bookings/{id}/reschedule.",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "notes": {
          "type": "string",
          "maxLength": 2000
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "Another staff member; \"any\" = the first free one. The time must be free for them (409 booking_slot_taken)."
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "Replaces the extra fields kept with the booking."
        }
      }
    },
    "BookingRescheduleRequest": {
      "type": "object",
      "required": [
        "start"
      ],
      "properties": {
        "start": {
          "type": "string",
          "example": "2026-11-12T10:00",
          "description": "A free slot (GET /bookings/availability or /bookings/next): Local time in the business time zone, yyyy-MM-ddTHH:mm."
        },
        "provider_id": {
          "type": "string",
          "example": "maria",
          "description": "Left out: the booking's own staff member. \"any\": the first free one."
        },
        "notify": {
          "type": "boolean",
          "default": true,
          "description": "Tell the customer on WhatsApp (a text inside their 24 hour window, else the confirmation template)."
        },
        "scope": {
          "type": "string",
          "enum": [
            "one",
            "following"
          ],
          "default": "one",
          "description": "following: this booking and the later ones of its series move by the same time difference (each checked; the customer gets one message); the answer adds series { id, moved, skipped }."
        }
      }
    },
    "CallingSettings": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "description": "ENABLED or DISABLED."
        },
        "call_icon_visibility": {
          "type": "string",
          "description": "DEFAULT or DISABLE_ALL."
        },
        "call_icons": {
          "type": "object",
          "properties": {
            "restrict_to_user_countries": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "call_hours": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string"
            },
            "timezone_id": {
              "type": "string"
            },
            "weekly_operating_hours": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "day_of_week": {
                    "type": "string"
                  },
                  "open_time": {
                    "type": "string"
                  },
                  "close_time": {
                    "type": "string"
                  }
                }
              }
            },
            "holiday_schedule": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": "string"
                  },
                  "start_time": {
                    "type": "string"
                  },
                  "end_time": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "additionalProperties": true
        },
        "callback_permission_status": {
          "type": "string",
          "description": "ENABLED: a user who calls grants call-back permission."
        },
        "srtp_key_exchange_protocol": {
          "type": "string",
          "description": "DTLS or SDES."
        },
        "sip": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string"
            },
            "servers": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "hostname": {
                    "type": "string"
                  },
                  "port": {
                    "type": "integer"
                  }
                },
                "additionalProperties": true
              }
            }
          },
          "additionalProperties": true
        },
        "video": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string"
            }
          }
        },
        "audio": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string"
            }
          }
        }
      },
      "description": "Meta's calling settings object, passed as it is.",
      "additionalProperties": true
    },
    "CallSettingsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "c4l1s"
        },
        "settings": {
          "type": "object",
          "properties": {
            "calling": {
              "$ref": "#/definitions/CallingSettings"
            },
            "storage_configuration": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            },
            "payload_encryption": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          },
          "additionalProperties": true
        }
      },
      "required": [
        "success",
        "request_id",
        "settings"
      ]
    },
    "CallSettingsUpdate": {
      "type": "object",
      "properties": {
        "calling": {
          "$ref": "#/definitions/CallingSettings"
        }
      },
      "required": [
        "calling"
      ],
      "description": "Or the calling object itself. Settings left out stay as they are."
    },
    "CallSettingsUpdateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "c4l1s"
        },
        "updated": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "calling": {
          "$ref": "#/definitions/CallingSettings"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "CallRequest": {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "connect",
            "pre_accept",
            "accept",
            "reject",
            "terminate",
            "media_update"
          ]
        },
        "to": {
          "type": "string",
          "description": "connect: the contact's number or business-scoped user id (sent as recipient)."
        },
        "recipient": {
          "type": "string",
          "description": "Instead of to: a business-scoped user id."
        },
        "call_id": {
          "type": "string",
          "description": "Every action but connect: the call's id (call.incoming / call.status)."
        },
        "session": {
          "type": "object",
          "properties": {
            "sdp_type": {
              "type": "string",
              "enum": [
                "offer",
                "answer"
              ]
            },
            "sdp": {
              "type": "string",
              "description": "RFC 8866 SDP."
            }
          },
          "required": [
            "sdp_type",
            "sdp"
          ]
        },
        "biz_opaque_callback_data": {
          "type": "string",
          "maxLength": 512
        },
        "recording": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string"
            },
            "purpose": {
              "type": "string"
            },
            "announcement_language": {
              "type": "string"
            }
          }
        },
        "transcription": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string"
            },
            "purpose": {
              "type": "string"
            },
            "announcement_language": {
              "type": "string"
            }
          }
        },
        "messaging_product": {
          "type": "string",
          "description": "Meta's body: accepted and ignored."
        }
      },
      "required": [
        "action"
      ],
      "description": "Meta's own body. connect needs to + session (offer); pre_accept / accept need call_id + session (answer)."
    },
    "CallResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "c4l1s"
        },
        "action": {
          "type": "string"
        },
        "call_id": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "CallPermissionResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "c4l1s"
        },
        "contact": {
          "type": "string"
        },
        "permission": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "description": "no_permission, temporary or permanent (Meta's call_permissions)."
            },
            "expires_at": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "action_name": {
                "type": "string",
                "enum": [
                  "start_call",
                  "send_call_permission_request"
                ]
              },
              "can_perform_action": {
                "type": "boolean"
              },
              "limits": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "time_period": {
                      "type": "string"
                    },
                    "max_allowed": {
                      "type": "integer"
                    },
                    "current_usage": {
                      "type": "integer"
                    },
                    "limit_expiration_time": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "EventFeedResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/WebhookEvent"
          },
          "description": "Oldest first. Each is the JSON a webhook gets, with the same id (a webhook's X-App2email-Delivery)."
        },
        "count": {
          "type": "integer"
        },
        "cursor": {
          "type": "string",
          "example": "ec_184467",
          "description": "Pass it as ?after= on the next call. It moves on even when a filter left every event out."
        },
        "has_more": {
          "type": "boolean",
          "description": "true: call again at once with the cursor, there is more."
        },
        "feed": {
          "type": "object",
          "properties": {
            "on": {
              "type": "boolean"
            },
            "started": {
              "type": "boolean",
              "description": "true: this call switched the number's feed on. Events from before it were not kept."
            },
            "kept_hours": {
              "type": "integer",
              "example": 72
            },
            "waited": {
              "type": "boolean",
              "description": "true: the answer waited for an event (\"wait\")."
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowValidationError": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        },
        "error_type": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "line_start": {
          "type": "integer"
        },
        "line_end": {
          "type": "integer"
        },
        "column_start": {
          "type": "integer"
        },
        "column_end": {
          "type": "integer"
        },
        "pointers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "Flow": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "DRAFT",
            "PUBLISHED",
            "DEPRECATED",
            "BLOCKED",
            "THROTTLED"
          ]
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "SIGN_UP",
              "SIGN_IN",
              "APPOINTMENT_BOOKING",
              "LEAD_GENERATION",
              "CONTACT_US",
              "CUSTOMER_SUPPORT",
              "SURVEY",
              "OTHER"
            ]
          }
        },
        "validation_errors": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/FlowValidationError"
          }
        },
        "json_version": {
          "type": "string"
        },
        "data_api_version": {
          "type": "string"
        },
        "endpoint_uri": {
          "type": "string"
        },
        "health_status": {
          "type": "object",
          "additionalProperties": true,
          "description": "can_send_message (AVAILABLE | LIMITED | BLOCKED) per entity, with errors."
        },
        "key": {
          "type": "string",
          "example": "booking",
          "description": "GET /flows only: one of this number's Book-and-Pay Flows; POST /flows/{key}/send takes the key. Left out for other Flows."
        },
        "can_send": {
          "type": "boolean",
          "description": "GET /flows, a Book-and-Pay Flow: POST /flows/{key}/send works now (enabled and published)."
        },
        "booking_flow": {
          "$ref": "#/definitions/BookingFlow",
          "description": "GET /flows, a Book-and-Pay Flow: the Flow as the Book-and-Pay section has it (status in its words)."
        }
      }
    },
    "FlowListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flows": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Flow"
          }
        },
        "next_cursor": {
          "type": "string",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "Flows in this answer."
        },
        "enabled": {
          "type": "boolean",
          "description": "Book-and-Pay is switched on for the number. Left out when the plan does not include Book-and-Pay."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowCreateRequest": {
      "type": "object",
      "required": [
        "name",
        "categories"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200,
          "description": "Internal name; customers do not see it."
        },
        "categories": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "enum": [
              "SIGN_UP",
              "SIGN_IN",
              "APPOINTMENT_BOOKING",
              "LEAD_GENERATION",
              "CONTACT_US",
              "CUSTOMER_SUPPORT",
              "SURVEY",
              "OTHER"
            ]
          }
        },
        "flow_json": {
          "type": "object",
          "additionalProperties": true,
          "description": "The Flow JSON (version, screens), as an object or a string. Max 10 MB."
        },
        "publish": {
          "type": "boolean",
          "description": "true (with flow_json): published at once. Cannot be undone."
        },
        "clone_flow_id": {
          "type": "string",
          "description": "Copy this flow (of the same account)."
        },
        "endpoint_uri": {
          "type": "string",
          "format": "uri",
          "description": "https URL of your data endpoint, for flows that use one."
        }
      }
    },
    "FlowCreateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "status": {
              "type": "string"
            }
          }
        },
        "validation_errors": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/FlowValidationError"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowDetailResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow": {
          "$ref": "#/definitions/Flow"
        }
      }
    },
    "FlowUpdateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "SIGN_UP",
              "SIGN_IN",
              "APPOINTMENT_BOOKING",
              "LEAD_GENERATION",
              "CONTACT_US",
              "CUSTOMER_SUPPORT",
              "SURVEY",
              "OTHER"
            ]
          }
        },
        "endpoint_uri": {
          "type": "string",
          "format": "uri"
        },
        "application_id": {
          "type": "string",
          "description": "The Meta app connected to a flow with an endpoint."
        }
      }
    },
    "FlowUpdateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow_id": {
          "type": "string"
        },
        "changed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "type": "string",
          "description": "Only when the flow was PUBLISHED: it is a DRAFT again."
        }
      }
    },
    "FlowDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "FlowJsonResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow_id": {
          "type": "string"
        },
        "flow_json": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "FlowJsonUploadResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow_id": {
          "type": "string"
        },
        "validation_errors": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/FlowValidationError"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowStateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "previous_status": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowPreviewResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "flow_id": {
          "type": "string"
        },
        "preview_url": {
          "type": "string",
          "format": "uri"
        },
        "expires_at": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowEncryptionKeyResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "public_key": {
          "type": "string",
          "nullable": true
        },
        "signature_status": {
          "type": "string",
          "enum": [
            "VALID",
            "MISMATCH"
          ],
          "nullable": true
        },
        "set_by": {
          "type": "string",
          "enum": [
            "bookings",
            "other"
          ],
          "nullable": true,
          "description": "bookings: the key Book-and-Pay made for its Flows (PUT answers 409 then). other: any other key. Left out without a key."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FlowEncryptionKeyRequest": {
      "type": "object",
      "required": [
        "public_key"
      ],
      "properties": {
        "public_key": {
          "type": "string",
          "description": "A 2048-bit RSA public key, PEM. Never the private key."
        }
      }
    },
    "FlowEncryptionKeySetResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "MediaMultipartUpload": {
      "type": "object",
      "required": [
        "file"
      ],
      "properties": {
        "file": {
          "type": "string",
          "format": "binary",
          "description": "The file."
        },
        "type": {
          "type": "string",
          "example": "image",
          "description": "Optional: image, video, document, audio or sticker, or a MIME type (Meta's own form). Left out: from the file."
        },
        "voice": {
          "type": "boolean",
          "description": "Audio: check it is a voice message (Ogg with OPUS)."
        }
      }
    },
    "MediaInfoResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "media": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "stored",
                "whatsapp"
              ]
            },
            "mime_type": {
              "type": "string"
            },
            "file_size": {
              "type": "integer"
            },
            "sha256": {
              "type": "string"
            },
            "filename": {
              "type": "string",
              "description": "stored only."
            },
            "message_id": {
              "type": "string",
              "description": "stored only."
            },
            "whatsapp_media_id": {
              "type": "string",
              "description": "stored only: WhatsApp's id of the received file (valid 7 days)."
            }
          }
        }
      }
    },
    "MediaDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "media_id": {
          "type": "string"
        },
        "deleted": {
          "type": "boolean"
        }
      }
    },
    "AudioContent": {
      "type": "object",
      "description": "aac, amr, mp3, m4a or ogg (OPUS), up to 16 MB. No caption.",
      "properties": {
        "link": {
          "type": "string",
          "format": "uri",
          "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "The file, base64 encoded."
        },
        "id": {
          "type": "string",
          "description": "A media id from POST /media."
        },
        "filename": {
          "type": "string"
        },
        "mime_type": {
          "type": "string"
        },
        "voice": {
          "type": "boolean",
          "description": "true: a voice message (play button, transcript). Ogg with the OPUS codec only; app2email does not convert."
        }
      }
    },
    "StickerContent": {
      "type": "object",
      "description": "WebP only: up to 100 KB static, 500 KB animated. No caption.",
      "properties": {
        "link": {
          "type": "string",
          "format": "uri",
          "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "The file, base64 encoded."
        },
        "id": {
          "type": "string",
          "description": "A media id from POST /media."
        },
        "filename": {
          "type": "string"
        },
        "mime_type": {
          "type": "string"
        }
      }
    },
    "LocationContent": {
      "type": "object",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "example": -33.8568
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "example": 151.2153
        },
        "name": {
          "type": "string",
          "example": "Sydney Opera House"
        },
        "address": {
          "type": "string",
          "example": "Bennelong Point, Sydney NSW 2000"
        }
      }
    },
    "ContactCard": {
      "type": "object",
      "required": [
        "name"
      ],
      "description": "One vCard, as WhatsApp Cloud API.",
      "properties": {
        "name": {
          "type": "object",
          "required": [
            "formatted_name"
          ],
          "properties": {
            "formatted_name": {
              "type": "string",
              "example": "Jane Citizen"
            },
            "first_name": {
              "type": "string"
            },
            "last_name": {
              "type": "string"
            },
            "middle_name": {
              "type": "string"
            },
            "prefix": {
              "type": "string"
            },
            "suffix": {
              "type": "string"
            }
          }
        },
        "phones": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "phone": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "example": "CELL"
              },
              "wa_id": {
                "type": "string"
              }
            }
          }
        },
        "emails": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            }
          }
        },
        "addresses": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "org": {
          "type": "object",
          "properties": {
            "company": {
              "type": "string"
            },
            "department": {
              "type": "string"
            },
            "title": {
              "type": "string"
            }
          }
        },
        "urls": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            }
          }
        },
        "birthday": {
          "type": "string",
          "example": "1990-01-31"
        }
      }
    },
    "ReactionContent": {
      "type": "object",
      "required": [
        "message_id",
        "emoji"
      ],
      "properties": {
        "message_id": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
          "description": "A message the contact sent, up to 30 days old."
        },
        "emoji": {
          "type": "string",
          "example": "👍",
          "description": "One emoji. \"\" removes your reaction."
        }
      }
    },
    "SendContact": {
      "type": "object",
      "description": "WhatsApp's contacts[] of the send answer.",
      "properties": {
        "input": {
          "type": "string",
          "example": "61412345678"
        },
        "wa_id": {
          "type": "string",
          "example": "61412345678"
        },
        "user_id": {
          "type": "string",
          "example": "AU.13491208655302741918",
          "description": "The business-scoped user id, when WhatsApp gives one."
        }
      }
    },
    "MarkReadRequest": {
      "type": "object",
      "required": [
        "message_id"
      ],
      "properties": {
        "message_id": {
          "type": "string",
          "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
          "description": "A message the contact sent, up to 30 days old."
        },
        "typing": {
          "type": "boolean",
          "default": false,
          "description": "true: also the typing indicator (25 seconds or until your reply)."
        },
        "dry_run": {
          "type": "boolean",
          "default": false
        }
      }
    },
    "MarkReadResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "message_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "read",
            "dry_run"
          ]
        },
        "typing_indicator": {
          "type": "boolean"
        },
        "sandbox": {
          "type": "boolean"
        },
        "dry_run": {
          "type": "boolean"
        },
        "whatsapp_message": {
          "type": "object",
          "additionalProperties": true,
          "description": "Dry run only."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "MarketingStatusResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "marketing": {
          "type": "object",
          "properties": {
            "route": {
              "type": "string",
              "enum": [
                "auto",
                "cloud_api",
                "mm_api"
              ],
              "description": "The number's setting messages.marketing_route."
            },
            "effective_route": {
              "type": "string",
              "enum": [
                "cloud_api",
                "mm_api"
              ],
              "description": "Where a marketing template goes now."
            },
            "onboarding_status": {
              "type": "string",
              "example": "ONBOARDED",
              "description": "WhatsApp's marketing_messages_onboarding_status (ELIGIBLE, ONBOARDED, ...)."
            },
            "cloud_api_marketing_disabled": {
              "type": "boolean",
              "description": "The account's disable_marketing_messages_on_cloud_api switch (null: WhatsApp did not give it)."
            },
            "checked_at": {
              "type": "string",
              "format": "date-time"
            },
            "warning": {
              "type": "string"
            }
          }
        }
      }
    },
    "BlockUsersRequest": {
      "type": "object",
      "required": [
        "users"
      ],
      "properties": {
        "users": {
          "type": "array",
          "maxItems": 1000,
          "items": {
            "type": "string"
          },
          "description": "Phone numbers (country code, digits) or business-scoped user ids. Meta's own block_users list works too."
        }
      }
    },
    "BlockedUser": {
      "type": "object",
      "properties": {
        "input": {
          "type": "string"
        },
        "wa_id": {
          "type": "string"
        },
        "user_id": {
          "type": "string"
        }
      }
    },
    "BlockFailure": {
      "type": "object",
      "properties": {
        "input": {
          "type": "string"
        },
        "wa_id": {
          "type": "string"
        },
        "user_id": {
          "type": "string"
        },
        "error": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "how_to_fix": {
              "type": "string"
            },
            "whatsapp_code": {
              "type": "integer"
            }
          }
        }
      }
    },
    "BlockUsersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "false when some users failed (HTTP 207)."
        },
        "request_id": {
          "type": "string"
        },
        "blocked": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BlockedUser"
          },
          "description": "POST only."
        },
        "unblocked": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BlockedUser"
          },
          "description": "DELETE only."
        },
        "failed": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BlockFailure"
          }
        }
      }
    },
    "BlockedListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "blocked": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/BlockedUser"
          }
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string"
        }
      }
    },
    "ContactBookResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "bsuid": {
          "type": "string"
        },
        "present": {
          "type": "boolean",
          "description": "GET: WhatsApp's contact book has a phone number for this id (never the number itself)."
        },
        "deleted": {
          "type": "boolean",
          "description": "DELETE: there was an entry and it is gone."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "NumberHealth": {
      "type": "object",
      "properties": {
        "can_send_message": {
          "type": "string",
          "enum": [
            "AVAILABLE",
            "LIMITED",
            "BLOCKED"
          ],
          "description": "WhatsApp's verdict for the number, its WABA, business and app together."
        },
        "entities": {
          "type": "array",
          "description": "Meta's health_status.entities: one per PHONE_NUMBER, WABA, BUSINESS, APP, with errors and how to fix them.",
          "items": {
            "type": "object",
            "properties": {
              "entity_type": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "can_send_message": {
                "type": "string"
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "error_code": {
                      "type": "integer"
                    },
                    "error_description": {
                      "type": "string"
                    },
                    "possible_solution": {
                      "type": "string"
                    }
                  }
                }
              },
              "additional_info": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "display_phone_number": {
          "type": "string"
        },
        "verified_name": {
          "type": "string"
        },
        "quality_rating": {
          "type": "string",
          "enum": [
            "GREEN",
            "YELLOW",
            "RED",
            "NA",
            "UNKNOWN"
          ]
        },
        "messaging_limit": {
          "type": "string",
          "description": "The business portfolio's limit of contacts outside the service window per 24 h, eg TIER_2K, TIER_UNLIMITED."
        },
        "throughput": {
          "type": "string",
          "description": "STANDARD (80 messages/s), HIGH (1,000 messages/s) or NOT_APPLICABLE."
        },
        "status": {
          "type": "string",
          "description": "CONNECTED, DISCONNECTED, PENDING, FLAGGED, RESTRICTED, RATE_LIMITED ..."
        },
        "name_status": {
          "type": "string",
          "description": "Review of verified_name: APPROVED, AVAILABLE_WITHOUT_REVIEW, DECLINED, EXPIRED, PENDING_REVIEW, NONE."
        },
        "new_display_name": {
          "type": "string",
          "description": "A requested display name under review (PUT /profile/display-name)."
        },
        "new_name_status": {
          "type": "string"
        },
        "code_verification_status": {
          "type": "string",
          "enum": [
            "VERIFIED",
            "UNVERIFIED",
            "EXPIRED"
          ]
        },
        "account_mode": {
          "type": "string",
          "enum": [
            "SANDBOX",
            "LIVE"
          ]
        },
        "is_official_business_account": {
          "type": "boolean"
        },
        "coexistence": {
          "type": "boolean",
          "description": "true: the number also runs in the WhatsApp Business app (20 messages/s at most)."
        }
      }
    },
    "NumberHealthResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "health": {
          "$ref": "#/definitions/NumberHealth"
        },
        "fetched_at": {
          "type": "string",
          "format": "date-time",
          "description": "When WhatsApp was asked (answers are kept 60 s)."
        }
      },
      "required": [
        "success",
        "request_id",
        "health"
      ]
    },
    "IdentityCheckRequest": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        }
      },
      "required": [
        "enabled"
      ]
    },
    "IdentityCheckResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "identity_check": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            }
          }
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "BusinessProfile": {
      "type": "object",
      "properties": {
        "about": {
          "type": "string",
          "maxLength": 139
        },
        "address": {
          "type": "string",
          "maxLength": 256
        },
        "description": {
          "type": "string",
          "maxLength": 512
        },
        "email": {
          "type": "string",
          "maxLength": 128
        },
        "profile_picture_url": {
          "type": "string",
          "description": "Meta's link to the current photo (read only)."
        },
        "websites": {
          "type": "array",
          "maxItems": 2,
          "items": {
            "type": "string"
          }
        },
        "vertical": {
          "type": "string",
          "enum": [
            "ALCOHOL",
            "APPAREL",
            "AUTO",
            "BEAUTY",
            "EDU",
            "ENTERTAIN",
            "EVENT_PLAN",
            "FINANCE",
            "GOVT",
            "GROCERY",
            "HEALTH",
            "HOTEL",
            "NONPROFIT",
            "ONLINE_GAMBLING",
            "OTC_DRUGS",
            "OTHER",
            "PHYSICAL_GAMBLING",
            "PROF_SERVICES",
            "RESTAURANT",
            "RETAIL",
            "TRAVEL"
          ]
        }
      }
    },
    "BusinessProfileUpdate": {
      "type": "object",
      "properties": {
        "about": {
          "type": "string",
          "minLength": 1,
          "maxLength": 139
        },
        "address": {
          "type": "string",
          "maxLength": 256
        },
        "description": {
          "type": "string",
          "maxLength": 512
        },
        "email": {
          "type": "string",
          "maxLength": 128
        },
        "websites": {
          "type": "array",
          "maxItems": 2,
          "items": {
            "type": "string"
          }
        },
        "vertical": {
          "type": "string"
        },
        "profile_picture_handle": {
          "type": "string",
          "description": "A Resumable Upload handle (Meta's body). PUT /profile/photo makes one from a link."
        }
      },
      "description": "Only the fields to change. messaging_product is accepted and ignored."
    },
    "BusinessProfileResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "profile": {
          "$ref": "#/definitions/BusinessProfile"
        }
      },
      "required": [
        "success",
        "request_id",
        "profile"
      ]
    },
    "BusinessProfileUpdateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "updated": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "profile": {
          "$ref": "#/definitions/BusinessProfile"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ProfilePhotoRequest": {
      "type": "object",
      "properties": {
        "link": {
          "type": "string",
          "format": "uri",
          "description": "Public http(s) link to a JPG or PNG image, up to 5 MB."
        }
      },
      "required": [
        "link"
      ]
    },
    "ProfilePhotoResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "updated": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "link": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "DisplayNameRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 3,
          "maxLength": 512
        }
      },
      "required": [
        "name"
      ]
    },
    "DisplayNameResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "display_name": {
          "type": "object",
          "properties": {
            "current": {
              "type": "string"
            },
            "requested": {
              "type": "string"
            },
            "status": {
              "type": "string"
            }
          }
        },
        "next_step": {
          "type": "string",
          "enum": [
            "wait_for_review"
          ]
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "OfficialBusinessAccount": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "PENDING",
            "APPROVED",
            "REJECTED",
            "UNDER_REVIEW",
            "EXPIRED",
            "CANCELLED"
          ]
        },
        "status_message": {
          "type": "string"
        }
      }
    },
    "OfficialBusinessAccountRequest": {
      "type": "object",
      "properties": {
        "business_website_url": {
          "type": "string",
          "format": "uri"
        },
        "primary_country_of_operation": {
          "type": "string"
        },
        "primary_language": {
          "type": "string"
        },
        "parent_business_or_brand": {
          "type": "string"
        },
        "supporting_links": {
          "type": "array",
          "minItems": 5,
          "maxItems": 10,
          "items": {
            "type": "string"
          },
          "description": "Articles about the business (not paid or own content)."
        },
        "additional_supporting_information": {
          "type": "string"
        }
      },
      "required": [
        "business_website_url",
        "primary_country_of_operation"
      ]
    },
    "OfficialBusinessAccountResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "official_business_account": {
          "$ref": "#/definitions/OfficialBusinessAccount"
        },
        "tracking_id": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "IndiaCompliance": {
      "type": "object",
      "properties": {
        "entity_name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 128
        },
        "entity_type": {
          "type": "string",
          "enum": [
            "LIMITED_LIABILITY_PARTNERSHIP",
            "SOLE_PROPRIETORSHIP",
            "PARTNERSHIP",
            "PUBLIC_COMPANY",
            "PRIVATE_COMPANY",
            "OTHER"
          ]
        },
        "entity_type_custom": {
          "type": "string",
          "description": "Needed with entity_type OTHER, refused with any other."
        },
        "is_registered": {
          "type": "boolean",
          "description": "Only with entity_type OTHER or PARTNERSHIP."
        },
        "grievance_officer_details": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "email": {
              "type": "string"
            },
            "mobile_number": {
              "type": "string"
            },
            "landline_number": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "email"
          ]
        },
        "customer_care_details": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string"
            },
            "mobile_number": {
              "type": "string"
            },
            "landline_number": {
              "type": "string"
            }
          },
          "required": [
            "email"
          ]
        }
      },
      "required": [
        "entity_name",
        "entity_type",
        "grievance_officer_details",
        "customer_care_details"
      ]
    },
    "IndiaComplianceResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "india_compliance": {
          "$ref": "#/definitions/IndiaCompliance"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "UsernameRequest": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string",
          "pattern": "^[a-z0-9._]{3,35}$"
        },
        "transfer_action": {
          "type": "string",
          "enum": [
            "none",
            "force_transfer"
          ],
          "description": "force_transfer: move it here from another number of the same business."
        }
      },
      "required": [
        "username"
      ]
    },
    "UsernameResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "username": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "approved",
            "reserved",
            "none"
          ]
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "UsernameDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "deleted": {
          "type": "boolean"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "UsernameSuggestionsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "suggestions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "count": {
          "type": "integer"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ConversationStarters": {
      "type": "object",
      "properties": {
        "prompts": {
          "type": "array",
          "maxItems": 4,
          "items": {
            "type": "string",
            "maxLength": 80
          },
          "description": "Ice breakers. No emoji. [] removes them."
        },
        "commands": {
          "type": "array",
          "maxItems": 30,
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 32
              },
              "description": {
                "type": "string",
                "maxLength": 256
              }
            },
            "required": [
              "name",
              "description"
            ]
          },
          "description": "Slash commands. No emoji. [] removes them. Meta's command_name / command_description work too."
        },
        "welcome_message": {
          "type": "boolean",
          "description": "Meta's enable_welcome_message: a request_welcome message when a user opens a chat for the first time."
        }
      }
    },
    "ConversationStartersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "conversation_starters": {
          "$ref": "#/definitions/ConversationStarters"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "QrCode": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "prefilled_message": {
          "type": "string",
          "maxLength": 140
        },
        "deep_link_url": {
          "type": "string"
        },
        "qr_image_url": {
          "type": "string",
          "description": "Link to the image (svg or png), when asked for."
        }
      }
    },
    "QrCodeCreateRequest": {
      "type": "object",
      "properties": {
        "prefilled_message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 140
        },
        "image": {
          "type": "string",
          "enum": [
            "svg",
            "png"
          ],
          "default": "svg"
        }
      },
      "required": [
        "prefilled_message"
      ]
    },
    "QrCodeUpdateRequest": {
      "type": "object",
      "properties": {
        "prefilled_message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 140
        }
      },
      "required": [
        "prefilled_message"
      ]
    },
    "QrCodeListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "qr_codes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/QrCode"
          }
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "QrCodeResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "qr_code": {
          "$ref": "#/definitions/QrCode"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "QrCodeDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "deleted": {
          "type": "boolean"
        },
        "code": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "CommerceSettings": {
      "type": "object",
      "properties": {
        "cart_enabled": {
          "type": "boolean"
        },
        "catalog_visible": {
          "type": "boolean"
        }
      }
    },
    "CommerceSettingsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "commerce": {
          "$ref": "#/definitions/CommerceSettings"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "CatalogRequest": {
      "type": "object",
      "properties": {
        "catalog_id": {
          "type": "string",
          "pattern": "^[0-9]{5,32}$"
        }
      },
      "required": [
        "catalog_id"
      ]
    },
    "CatalogResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string",
          "example": "k3x9a"
        },
        "catalog": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "connected": {
          "type": "boolean"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "Partner": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "suspended",
            "closed"
          ]
        },
        "slug": {
          "type": "string"
        },
        "brand_name": {
          "type": "string",
          "nullable": true
        },
        "site_url": {
          "type": "string",
          "description": "Your site: the active own domain, else https://<slug>.app2email.com."
        },
        "custom_domain": {
          "type": "string",
          "nullable": true
        },
        "domain_status": {
          "type": "string"
        },
        "fee_percent": {
          "type": "number",
          "description": "app2email's share of each client payment."
        },
        "stripe": {
          "type": "object",
          "properties": {
            "connected": {
              "type": "boolean"
            },
            "charges_enabled": {
              "type": "boolean"
            },
            "test_mode": {
              "type": "boolean"
            },
            "currency": {
              "type": "string",
              "nullable": true
            }
          }
        },
        "trial": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "messages": {
              "type": "integer"
            },
            "days": {
              "type": "integer"
            }
          }
        },
        "redirect_url": {
          "type": "string",
          "nullable": true,
          "description": "Where Finish of an onboarding link goes when the link names none."
        },
        "created": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    },
    "PartnerResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "partner": {
          "$ref": "#/definitions/Partner"
        },
        "key": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "scopes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "PartnerUpdateRequest": {
      "type": "object",
      "properties": {
        "redirect_url": {
          "type": "string",
          "nullable": true,
          "description": "https only. null removes it."
        },
        "trial": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "false: a new client number must buy a plan first."
            },
            "messages": {
              "type": "integer",
              "minimum": 10
            },
            "days": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365
            }
          }
        }
      }
    },
    "PartnerClient": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "nullable": true
        },
        "name": {
          "type": "string",
          "nullable": true
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "suspended"
          ]
        },
        "created": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "numbers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "numbers_count": {
          "type": "integer"
        }
      }
    },
    "PartnerClientsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "clients": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PartnerClient"
          }
        },
        "count": {
          "type": "integer"
        },
        "total": {
          "type": "integer"
        },
        "offset": {
          "type": "integer"
        },
        "limit": {
          "type": "integer"
        }
      }
    },
    "PartnerClientResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "client": {
          "$ref": "#/definitions/PartnerClient"
        }
      }
    },
    "PartnerClientCreateRequest": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 254
        },
        "name": {
          "type": "string",
          "maxLength": 100
        },
        "send_invite": {
          "type": "boolean",
          "default": true,
          "description": "true: the client gets your invitation e-mail (its link lets them choose a password)."
        },
        "redirect_url": {
          "type": "string",
          "description": "Where the invitation's Finish goes (https)."
        },
        "state": {
          "type": "string",
          "maxLength": 200
        }
      },
      "required": [
        "email"
      ]
    },
    "PartnerClientCreated": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "client": {
          "$ref": "#/definitions/PartnerClient"
        },
        "invite": {
          "type": "object",
          "properties": {
            "sent": {
              "type": "boolean"
            },
            "expires": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "message": {
              "type": "string"
            }
          },
          "nullable": true
        }
      }
    },
    "PartnerClientUpdateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 100
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "suspended"
          ],
          "description": "suspended: logged out of your site, cannot log in."
        }
      }
    },
    "PartnerClientUpdated": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "client": {
          "$ref": "#/definitions/PartnerClient"
        },
        "changes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "PartnerSubscription": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "client_id": {
          "type": "string"
        },
        "number": {
          "type": "string",
          "nullable": true
        },
        "tier_id": {
          "type": "string"
        },
        "tier_name": {
          "type": "string"
        },
        "interval": {
          "type": "string",
          "enum": [
            "month",
            "year",
            "none"
          ]
        },
        "messages_per_month": {
          "type": "integer"
        },
        "price": {
          "type": "object",
          "properties": {
            "amount_minor": {
              "type": "integer"
            },
            "currency": {
              "type": "string"
            }
          }
        },
        "status": {
          "type": "string",
          "description": "Stripe's status: active, trialing, past_due, canceled ..."
        },
        "source": {
          "type": "string",
          "enum": [
            "stripe",
            "free",
            "comp"
          ]
        },
        "cancel_at_period_end": {
          "type": "boolean"
        },
        "current_period_start": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "current_period_end": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "is_current": {
          "type": "boolean"
        },
        "canceled_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "ended_reason": {
          "type": "string",
          "nullable": true
        },
        "test_mode": {
          "type": "boolean",
          "description": "Bought through Stripe's test mode (the test site)."
        }
      }
    },
    "PartnerNumber": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string"
        },
        "display_number": {
          "type": "string",
          "nullable": true
        },
        "name": {
          "type": "string",
          "nullable": true
        },
        "client_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "live",
            "pending_payment",
            "not_live"
          ],
          "description": "live: LIVE on a plan with the API. pending_payment: no such plan. not_live: paused, expired or being connected."
        },
        "service_status": {
          "type": "string",
          "nullable": true
        },
        "plan": {
          "type": "string"
        },
        "features": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "nullable": true,
          "description": "The plan's features; null: app2email's own rules."
        },
        "api_allowed": {
          "type": "boolean"
        },
        "plan_messages": {
          "type": "object",
          "properties": {
            "total_sent": {
              "type": "integer"
            },
            "limit": {
              "type": "integer"
            }
          }
        },
        "billing_period_end": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "renewal_enabled": {
          "type": "boolean"
        },
        "subscription": {
          "$ref": "#/definitions/PartnerSubscription",
          "nullable": true
        }
      }
    },
    "PartnerNumbersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "numbers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PartnerNumber"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "PartnerNumberResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "$ref": "#/definitions/PartnerNumber"
        }
      }
    },
    "PartnerUsage": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string"
        },
        "client_id": {
          "type": "string"
        },
        "plan": {
          "type": "string"
        },
        "service_status": {
          "type": "string",
          "nullable": true
        },
        "billing_period": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "end": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            }
          }
        },
        "plan_messages": {
          "type": "object",
          "properties": {
            "whatsapp_sent": {
              "type": "integer"
            },
            "emails_sent": {
              "type": "integer"
            },
            "total_sent": {
              "type": "integer"
            },
            "limit": {
              "type": "integer"
            },
            "left": {
              "type": "integer"
            }
          }
        },
        "messages_received_this_billing_month": {
          "type": "integer"
        }
      }
    },
    "PartnerNumberUsageResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "usage": {
          "$ref": "#/definitions/PartnerUsage"
        }
      }
    },
    "PartnerClientUsageResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "client_id": {
          "type": "string"
        },
        "numbers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PartnerUsage"
          }
        },
        "totals": {
          "type": "object",
          "properties": {
            "total_sent": {
              "type": "integer"
            },
            "whatsapp_sent": {
              "type": "integer"
            },
            "emails_sent": {
              "type": "integer"
            },
            "messages_received": {
              "type": "integer"
            }
          }
        }
      }
    },
    "PartnerNumberKeysResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "keys": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AccountNumberKey"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "OnboardingLinkRequest": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "description": "Shown on the link's page."
        },
        "name": {
          "type": "string",
          "maxLength": 100
        },
        "client_id": {
          "type": "string",
          "description": "An existing client: only that client can finish it (a client with no password yet chooses one)."
        },
        "state": {
          "type": "string",
          "maxLength": 200,
          "description": "Comes back unchanged in the redirect."
        },
        "redirect_url": {
          "type": "string",
          "description": "https. Default: your redirect_url (PATCH /v1/partner); none: the client's dashboard."
        }
      }
    },
    "OnboardingLinkResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "link": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            },
            "expires": {
              "type": "string",
              "format": "date-time"
            },
            "client_id": {
              "type": "string",
              "nullable": true
            },
            "email": {
              "type": "string",
              "nullable": true
            },
            "state": {
              "type": "string",
              "nullable": true
            },
            "redirect_url": {
              "type": "string",
              "nullable": true
            }
          }
        },
        "message": {
          "type": "string"
        }
      }
    },
    "PartnerPayment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "client_id": {
          "type": "string",
          "nullable": true
        },
        "number_id": {
          "type": "integer",
          "nullable": true
        },
        "subscription_id": {
          "type": "integer",
          "nullable": true
        },
        "description": {
          "type": "string",
          "nullable": true
        },
        "amount_minor": {
          "type": "integer"
        },
        "refunded_minor": {
          "type": "integer"
        },
        "application_fee_minor": {
          "type": "integer"
        },
        "net_minor": {
          "type": "integer"
        },
        "currency": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "description": "paid, partially_refunded, refunded, disputed ..."
        },
        "billing_reason": {
          "type": "string",
          "nullable": true
        },
        "period_start": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "period_end": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "paid_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "stripe_invoice_id": {
          "type": "string",
          "nullable": true
        },
        "test_mode": {
          "type": "boolean"
        }
      }
    },
    "PartnerPaymentsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "mode": {
          "type": "string",
          "enum": [
            "live",
            "test"
          ]
        },
        "payments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PartnerPayment"
          }
        },
        "count": {
          "type": "integer"
        },
        "totals": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "currency": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              },
              "gross_minor": {
                "type": "integer"
              },
              "fee_minor": {
                "type": "integer"
              },
              "refunded_minor": {
                "type": "integer"
              },
              "net_minor": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "PartnerSubscriptionsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "mode": {
          "type": "string",
          "enum": [
            "live",
            "test"
          ]
        },
        "subscriptions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PartnerSubscription"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "Payment": {
      "type": "object",
      "description": "A payment row. kind booking: the online payment (or deposit) of an appointment; request: a one-off payment request; package: a prepaid package bought online. Money is a number in the payment's currency plus a label such as \"$40.00\". Also inside booking.paid, booking.refunded and payment.paid. ticket: the online payment of a ticket order (the order's payment.id).",
      "properties": {
        "id": {
          "type": "integer",
          "example": 15
        },
        "kind": {
          "type": "string",
          "enum": [
            "booking",
            "request",
            "package",
            "ticket"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "paid",
            "partly_refunded",
            "refunded",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "provider": {
          "type": "string",
          "enum": [
            "stripe",
            "paypal"
          ]
        },
        "amount": {
          "type": "number",
          "example": 40.0
        },
        "amount_label": {
          "type": "string",
          "example": "$40.00"
        },
        "full_label": {
          "type": "string",
          "description": "The price before a discount."
        },
        "discount_label": {
          "type": "string"
        },
        "coupon_code": {
          "type": "string"
        },
        "currency": {
          "type": "string",
          "example": "USD"
        },
        "refunded": {
          "type": "number"
        },
        "refunded_label": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "contact": {
          "type": "string"
        },
        "payer_name": {
          "type": "string"
        },
        "appointment_id": {
          "type": "integer",
          "nullable": true
        },
        "booking_reference": {
          "type": "string",
          "example": "BK-7Q3M2A"
        },
        "package_purchase_id": {
          "type": "integer",
          "nullable": true
        },
        "checkout_url": {
          "type": "string",
          "description": "The provider's checkout page while the payment is open. Empty otherwise."
        },
        "link_url": {
          "type": "string",
          "description": "A payment request's page on the business's booking site."
        },
        "last_error": {
          "type": "string"
        },
        "paid": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "refunded_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "PaymentResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "payment": {
          "$ref": "#/definitions/Payment"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "PaymentsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "payments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Payment"
          },
          "description": "Newest first."
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        },
        "currency": {
          "type": "string"
        }
      }
    },
    "PaymentLinkRequest": {
      "type": "object",
      "required": [
        "contact",
        "amount",
        "description"
      ],
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The customer's WhatsApp number with country code, digits only, or their business-scoped user id."
        },
        "amount": {
          "type": "number",
          "example": 40,
          "description": "In the business's payment currency (config.payments.currency)."
        },
        "description": {
          "type": "string",
          "example": "Deposit for your colour",
          "description": "Shown to the customer."
        },
        "booking_id": {
          "type": "string",
          "example": "BK-7Q3M2A",
          "description": "The appointment it is for (id or reference)."
        },
        "name": {
          "type": "string"
        },
        "send": {
          "type": "boolean",
          "default": false,
          "description": "Also send the link to the customer on WhatsApp (a message with a Pay button, only inside their 24 hour window)."
        }
      }
    },
    "PaymentLinkResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "payment": {
          "$ref": "#/definitions/Payment"
        },
        "url": {
          "type": "string",
          "example": "https://www.app2email.com/book/k3XbQ9rTzP2m",
          "description": "The page where the customer pays."
        },
        "sent": {
          "type": "boolean",
          "description": "The link was sent on WhatsApp."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "RefundRequest": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 10,
          "description": "A part of the money, in the payment's currency. Left out: everything that is left."
        }
      }
    },
    "BookingPaymentStatusRequest": {
      "type": "object",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "paid",
            "waived",
            "due"
          ],
          "description": "paid: taken outside app2email (cash, a terminal). waived: nothing to pay. due: still expected (the service's price is the amount when none is recorded)."
        }
      }
    },
    "PackageOnSale": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "ten-pack"
        },
        "name": {
          "type": "string",
          "example": "10 sessions"
        },
        "description": {
          "type": "string"
        },
        "sessions": {
          "type": "integer",
          "example": 10
        },
        "price_amount": {
          "type": "number",
          "example": 400
        },
        "price_label": {
          "type": "string",
          "example": "$400.00"
        },
        "valid_days": {
          "type": "integer",
          "description": "0 = never expires."
        },
        "services": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The services it covers. Empty: every service."
        }
      }
    },
    "PackagesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "packages": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PackageOnSale"
          }
        },
        "count": {
          "type": "integer"
        },
        "currency": {
          "type": "string"
        }
      }
    },
    "PackagePurchase": {
      "type": "object",
      "description": "Prepaid sessions a customer holds. Using one on a booking (POST /bookings with use_package) takes a session; a cancellation by the business gives it back. Also in package.purchased.",
      "properties": {
        "id": {
          "type": "integer",
          "example": 5
        },
        "contact": {
          "type": "string"
        },
        "contact_name": {
          "type": "string"
        },
        "package_id": {
          "type": "string"
        },
        "package_name": {
          "type": "string"
        },
        "services": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "sessions_total": {
          "type": "integer"
        },
        "sessions_used": {
          "type": "integer"
        },
        "sessions_left": {
          "type": "integer"
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "used_up",
            "expired",
            "refunded",
            "cancelled"
          ]
        },
        "payment_id": {
          "type": "integer",
          "nullable": true
        },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "PackagePurchasesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "purchases": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PackagePurchase"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "PackageGrantRequest": {
      "type": "object",
      "required": [
        "contact",
        "package_id"
      ],
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678"
        },
        "package_id": {
          "type": "string",
          "example": "ten-pack",
          "description": "One of GET /bookings/packages."
        },
        "sessions": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "description": "Default: the package's sessions."
        },
        "name": {
          "type": "string"
        }
      }
    },
    "PackageGrantResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "purchase": {
          "$ref": "#/definitions/PackagePurchase"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "CustomerSummary": {
      "type": "object",
      "properties": {
        "contact": {
          "type": "string",
          "example": "61412345678"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "visits": {
          "type": "integer"
        },
        "no_shows": {
          "type": "integer"
        },
        "upcoming": {
          "type": "integer"
        },
        "last_visit": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "next_start": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "packages_left": {
          "type": "integer"
        },
        "total_paid_label": {
          "type": "string",
          "example": "$120.00"
        }
      }
    },
    "CustomersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "customers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CustomerSummary"
          }
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        }
      }
    },
    "CustomerProfile": {
      "type": "object",
      "description": "Everything about one customer, for a prep brief or an agent: the contact (name, e-mail, tags, custom fields, consent), stats (visits, no-shows, cancellations, total paid, first seen, last visit), upcoming appointments and the past 50, internal notes and reminders, packages with sessions left, payments and the last 20 messages of the conversation.",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "customer": {
          "type": "object",
          "additionalProperties": true
        },
        "stats": {
          "type": "object",
          "additionalProperties": true
        },
        "upcoming": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "past": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Note"
          }
        },
        "reminders": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Note"
          },
          "description": "Notes with a remind_at that is due."
        },
        "packages": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PackagePurchase"
          }
        },
        "payments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Payment"
          }
        },
        "messages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "direction": {
                "type": "string",
                "enum": [
                  "in",
                  "out"
                ]
              },
              "text": {
                "type": "string"
              },
              "time": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    },
    "CustomerPatchRequest": {
      "type": "object",
      "description": "Any of these; what is left out stays. The e-mail also goes onto the customer's upcoming confirmed appointments.",
      "properties": {
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "custom_fields": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    },
    "CustomerResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "customer": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "CustomerEraseResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "erased": {
          "type": "boolean"
        },
        "note": {
          "type": "string"
        },
        "counts": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          },
          "description": "appointments, cancelled, notes, links, holds, votes, packages, payments."
        }
      }
    },
    "Poll": {
      "type": "object",
      "description": "A meeting poll: 2 to 10 possible times people vote on at the poll's page (url). The times are not held.",
      "properties": {
        "id": {
          "type": "integer",
          "example": 12
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "service_id": {
          "type": "string"
        },
        "provider_id": {
          "type": "string"
        },
        "duration_min": {
          "type": "integer"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "a"
              },
              "start": {
                "type": "string",
                "format": "date-time"
              },
              "end": {
                "type": "string",
                "format": "date-time"
              },
              "start_local": {
                "type": "string"
              },
              "end_local": {
                "type": "string"
              },
              "votes": {
                "type": "integer"
              },
              "voters": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "votes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "contact": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "choices": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "comment": {
                "type": "string"
              },
              "created": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        },
        "contact": {
          "type": "string",
          "description": "The main customer, when there is one."
        },
        "contact_name": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "open",
            "closed",
            "booked"
          ]
        },
        "chosen_option": {
          "type": "string"
        },
        "appointment_id": {
          "type": "integer",
          "nullable": true
        },
        "url": {
          "type": "string"
        },
        "closes": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "PollResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "poll": {
          "$ref": "#/definitions/Poll"
        },
        "url": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "PollsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "polls": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Poll"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "PollCreateRequest": {
      "type": "object",
      "required": [
        "title",
        "options"
      ],
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 120,
          "example": "Team planning"
        },
        "description": {
          "type": "string",
          "maxLength": 1000
        },
        "options": {
          "type": "array",
          "minItems": 2,
          "maxItems": 10,
          "items": {
            "type": "string"
          },
          "example": [
            "2026-11-12T10:00",
            "2026-11-12T14:00",
            "2026-11-13T09:00"
          ],
          "description": "Start times: local time in the business time zone (yyyy-MM-ddTHH:mm) or ISO 8601 with an offset. Each must be free now."
        },
        "service_id": {
          "type": "string",
          "example": "consultation",
          "description": "Its length is used. Give this or duration_min."
        },
        "duration_min": {
          "type": "integer",
          "minimum": 5,
          "maximum": 480
        },
        "provider_id": {
          "type": "string"
        },
        "contact": {
          "type": "string",
          "description": "The main customer: booking the poll then makes an appointment for them. Left out: the time is blocked."
        },
        "name": {
          "type": "string"
        },
        "closes_at": {
          "type": "string",
          "format": "date-time",
          "description": "When voting ends."
        }
      }
    },
    "PollBookRequest": {
      "type": "object",
      "required": [
        "option_id"
      ],
      "properties": {
        "option_id": {
          "type": "string",
          "example": "c",
          "description": "One of the poll's options[].id."
        },
        "notify": {
          "type": "boolean",
          "default": true,
          "description": "Tell the customer on WhatsApp (when the poll has a contact)."
        }
      }
    },
    "PollBookResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "poll": {
          "$ref": "#/definitions/Poll"
        },
        "booking": {
          "$ref": "#/definitions/Booking",
          "nullable": true
        },
        "block": {
          "$ref": "#/definitions/Block",
          "nullable": true
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ShopResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "shop": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "set_up": {
              "type": "boolean"
            },
            "enabled": {
              "type": "boolean",
              "description": "The shop takes orders."
            },
            "name": {
              "type": "string"
            },
            "preset": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            },
            "timezone": {
              "type": "string"
            },
            "page_url": {
              "type": "string"
            },
            "open_now": {
              "type": "boolean"
            },
            "paused": {
              "type": "boolean"
            },
            "pickup": {
              "type": "boolean"
            },
            "delivery": {
              "type": "boolean"
            },
            "browse": {
              "type": "string",
              "description": "How the chat lets customers order: page, flow or choose."
            },
            "counts": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "items": {
                  "type": "integer"
                },
                "active": {
                  "type": "integer"
                },
                "categories": {
                  "type": "integer"
                }
              }
            },
            "limits": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "items": {
                  "type": "integer"
                },
                "categories": {
                  "type": "integer"
                },
                "variants": {
                  "type": "integer"
                },
                "search_limit": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopSettingsResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "settings": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "slug": {
              "type": "string"
            },
            "page_url": {
              "type": "string"
            },
            "config": {
              "type": "object",
              "additionalProperties": true,
              "description": "The sections: business, money, tax, stock, catalog, fulfilment, pickup, delivery, checkout, payments, discounts, orders, notify, whatsapp."
            }
          }
        },
        "not_ready": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "After a change: what is still missing before the shop can take orders (empty = nothing)."
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopSettingsRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "config": {
          "type": "object",
          "additionalProperties": true,
          "description": "The sections to change, each with only the keys to change. An object inside a section is merged key by key; a list (hours of a day, delivery methods, discount codes) replaces the stored list."
        }
      },
      "required": [
        "config"
      ]
    },
    "ShopCategoriesResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "parent_id": {
                "type": "integer",
                "nullable": true
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "sort": {
                "type": "integer"
              },
              "hidden": {
                "type": "boolean"
              },
              "items": {
                "type": "integer"
              }
            }
          }
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopItem": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": "integer"
        },
        "sku": {
          "type": "string",
          "description": "Your own product code; unique in the shop, may be empty."
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "category_id": {
          "type": "integer",
          "nullable": true
        },
        "price": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "price_label": {
          "type": "string",
          "example": "$10.00"
        },
        "compare_at": {
          "type": "integer",
          "nullable": true,
          "description": "A higher \"was\" price in minor units, shown struck through."
        },
        "tax_class": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "hidden",
            "archived"
          ]
        },
        "has_variants": {
          "type": "boolean"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "attrs": {
          "type": "object",
          "additionalProperties": true,
          "description": "Attributes customers filter by, eg {\"colour\": \"Red\"}."
        },
        "allergens": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "dietary": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "track_stock": {
          "type": "boolean"
        },
        "stock_qty": {
          "type": "integer"
        },
        "low_stock_at": {
          "type": "integer",
          "nullable": true
        },
        "stock_state": {
          "type": "string",
          "description": "ok, low, out, untracked, or variants (the figures are on the variants)."
        },
        "daily_limit": {
          "type": "integer",
          "nullable": true
        },
        "sold_out_until": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "sold_out_now": {
          "type": "boolean"
        },
        "no_whatsapp": {
          "type": "boolean",
          "description": "true = shown on the order page only, never in a WhatsApp message."
        },
        "min_qty": {
          "type": "integer"
        },
        "max_qty": {
          "type": "integer",
          "description": "0 = no limit of its own."
        },
        "prep_minutes": {
          "type": "integer",
          "nullable": true
        },
        "sort": {
          "type": "integer"
        },
        "sold_count": {
          "type": "integer"
        },
        "image": {
          "type": "object",
          "nullable": true,
          "additionalProperties": true,
          "description": "The main picture's addresses by size (thumb, card, full)."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "variants": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "sku": {
                "type": "string"
              },
              "attrs": {
                "type": "object",
                "additionalProperties": true,
                "description": "What makes this version, eg {\"size\": \"M\", \"colour\": \"Red\"}."
              },
              "price": {
                "type": "integer",
                "nullable": true,
                "description": "Its own price in minor units; null = the item's price."
              },
              "price_effective": {
                "type": "integer",
                "description": "Whole minor units (cents): 1250 = 12.50."
              },
              "price_label": {
                "type": "string"
              },
              "track_stock": {
                "type": "boolean"
              },
              "stock_qty": {
                "type": "integer"
              },
              "stock_state": {
                "type": "string"
              },
              "barcode": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "hidden"
                ]
              },
              "sort": {
                "type": "integer"
              }
            }
          },
          "description": "Only in GET /shop/items/{id} and the answers of a save."
        },
        "option_group_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "option_groups": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "min_choices": {
                "type": "integer",
                "description": "How many the customer must choose at least (0 = optional)."
              },
              "max_choices": {
                "type": "integer",
                "description": "How many at most."
              },
              "options": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "price_delta": {
                      "type": "integer",
                      "description": "Added to the price, minor units."
                    },
                    "price_delta_label": {
                      "type": "string"
                    },
                    "sold_out_now": {
                      "type": "boolean"
                    },
                    "default_on": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "ShopItemsResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ShopItem"
          }
        },
        "total": {
          "type": "integer"
        },
        "total_capped": {
          "type": "boolean",
          "description": "true = there are more than total says."
        },
        "typo_match": {
          "type": "boolean"
        },
        "limit": {
          "type": "integer"
        },
        "offset": {
          "type": "integer"
        },
        "facets": {
          "type": "object",
          "nullable": true,
          "additionalProperties": true
        },
        "currency": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopItemResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "item": {
          "$ref": "#/definitions/ShopItem"
        },
        "currency": {
          "type": "string"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopItemRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 120
        },
        "price": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "description": {
          "type": "string",
          "maxLength": 2000
        },
        "sku": {
          "type": "string"
        },
        "category_id": {
          "type": "integer",
          "nullable": true
        },
        "compare_at": {
          "type": "integer",
          "nullable": true
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "hidden",
            "archived"
          ]
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "attrs": {
          "type": "object",
          "additionalProperties": true
        },
        "allergens": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "dietary": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "track_stock": {
          "type": "boolean"
        },
        "stock_qty": {
          "type": "integer",
          "minimum": 0
        },
        "low_stock_at": {
          "type": "integer",
          "nullable": true
        },
        "no_whatsapp": {
          "type": "boolean"
        },
        "min_qty": {
          "type": "integer"
        },
        "max_qty": {
          "type": "integer"
        },
        "prep_minutes": {
          "type": "integer",
          "nullable": true
        },
        "sort": {
          "type": "integer"
        },
        "option_group_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "variants": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "sku": {
                "type": "string"
              },
              "attrs": {
                "type": "object",
                "additionalProperties": true,
                "description": "What makes this version, eg {\"size\": \"M\", \"colour\": \"Red\"}."
              },
              "price": {
                "type": "integer",
                "nullable": true,
                "description": "Its own price in minor units; null = the item's price."
              },
              "price_effective": {
                "type": "integer",
                "description": "Whole minor units (cents): 1250 = 12.50."
              },
              "price_label": {
                "type": "string"
              },
              "track_stock": {
                "type": "boolean"
              },
              "stock_qty": {
                "type": "integer"
              },
              "stock_state": {
                "type": "string"
              },
              "barcode": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "hidden"
                ]
              },
              "sort": {
                "type": "integer"
              }
            }
          },
          "description": "The whole list: a stored variant that is left out is removed. Send id to keep a variant."
        }
      },
      "description": "A product. POST needs name and price; PUT changes only the keys sent."
    },
    "ShopStockRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "set",
            "add"
          ],
          "default": "set"
        },
        "value": {
          "type": "integer",
          "description": "The new figure (set) or the change (add; negative takes away)."
        },
        "variant_id": {
          "type": "integer",
          "nullable": true
        },
        "note": {
          "type": "string",
          "maxLength": 300
        },
        "start_tracking": {
          "type": "boolean",
          "description": "Switch stock counting on for an item that does not count yet."
        }
      },
      "required": [
        "value"
      ]
    },
    "ShopStockResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "item_id": {
          "type": "integer"
        },
        "variant_id": {
          "type": "integer",
          "nullable": true
        },
        "stock_qty": {
          "type": "integer"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopSoldOutRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "until": {
          "type": "string",
          "description": "on (until switched back), 1h, 2h, 4h, today, off (available again), or a later ISO 8601 time.",
          "example": "today"
        }
      },
      "required": [
        "until"
      ]
    },
    "ShopSoldOutResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "item_id": {
          "type": "integer"
        },
        "sold_out_until": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "sold_out_now": {
          "type": "boolean"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopOrder": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": "integer"
        },
        "reference": {
          "type": "string",
          "example": "SO-K7M2QX"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending_payment",
            "unconfirmed",
            "new",
            "accepted",
            "preparing",
            "ready",
            "out_for_delivery",
            "completed",
            "cancelled",
            "rejected",
            "expired"
          ],
          "description": "pending_payment = waits for its online payment; unconfirmed = a visitor of the order page has not confirmed on WhatsApp yet; new = waits for the shop to accept it."
        },
        "status_text": {
          "type": "string"
        },
        "source": {
          "type": "string",
          "enum": [
            "web",
            "chat",
            "flow",
            "counter",
            "api"
          ]
        },
        "fulfilment": {
          "type": "string",
          "enum": [
            "pickup",
            "delivery"
          ]
        },
        "asap": {
          "type": "boolean"
        },
        "due_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "due_label": {
          "type": "string"
        },
        "slot_label": {
          "type": "string"
        },
        "customer_name": {
          "type": "string"
        },
        "customer_phone": {
          "type": "string"
        },
        "customer_email": {
          "type": "string"
        },
        "contact_identity": {
          "type": "string",
          "description": "The customer's WhatsApp number (digits) or business-scoped user id."
        },
        "contact_verified": {
          "type": "boolean"
        },
        "address": {
          "type": "object",
          "additionalProperties": true,
          "description": "The delivery address; {} for a pickup."
        },
        "delivery_method": {
          "type": "string"
        },
        "delivery_zone": {
          "type": "string"
        },
        "note": {
          "type": "string"
        },
        "allergy_note": {
          "type": "string"
        },
        "items_count": {
          "type": "integer"
        },
        "items_text": {
          "type": "string",
          "example": "2 x Margherita, 1 x Cola"
        },
        "currency": {
          "type": "string"
        },
        "subtotal": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "discount": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "discount_code": {
          "type": "string"
        },
        "delivery_fee": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "fees": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "tip": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "tax": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "total": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "total_label": {
          "type": "string",
          "example": "$30.50"
        },
        "refunded": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "refundable": {
          "type": "integer",
          "description": "Whole minor units (cents): 1250 = 12.50."
        },
        "payment_state": {
          "type": "string",
          "enum": [
            "not_needed",
            "on_pickup",
            "on_delivery",
            "pending",
            "authorised",
            "paid",
            "part_refunded",
            "refunded",
            "released",
            "failed"
          ]
        },
        "payment_method": {
          "type": "string"
        },
        "payment_id": {
          "type": "integer",
          "nullable": true
        },
        "pickup_code": {
          "type": "string",
          "description": "The 4 characters the customer can say at the counter."
        },
        "order_url": {
          "type": "string",
          "description": "The customer's page of this order."
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What POST /shop/orders/{id}/action accepts for this order now."
        },
        "can_refund": {
          "type": "boolean"
        },
        "late": {
          "type": "boolean"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "accepted_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "ready_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "completed_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "cancelled_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "cancelled_by": {
          "type": "string"
        },
        "cancel_reason": {
          "type": "string"
        },
        "handed_by": {
          "type": "string"
        },
        "handed_method": {
          "type": "string"
        },
        "lines": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "item_id": {
                "type": "integer"
              },
              "variant_id": {
                "type": "integer",
                "nullable": true
              },
              "sku": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "variant_label": {
                "type": "string"
              },
              "options": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "group": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "price_delta": {
                      "type": "integer"
                    }
                  }
                }
              },
              "qty": {
                "type": "integer"
              },
              "unit_price": {
                "type": "integer",
                "description": "Whole minor units (cents): 1250 = 12.50."
              },
              "unit_price_label": {
                "type": "string"
              },
              "line_total": {
                "type": "integer",
                "description": "Whole minor units (cents): 1250 = 12.50."
              },
              "line_total_label": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "description": "Left out in lists."
        }
      },
      "description": "An order as the staff see it. Money in minor units."
    },
    "ShopOrdersResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "orders": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ShopOrder"
          }
        },
        "more": {
          "type": "boolean"
        },
        "next_before": {
          "type": "integer",
          "nullable": true,
          "description": "Send as before for the next page."
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopOrderResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "order": {
          "$ref": "#/definitions/ShopOrder"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "GET only: the history, newest last: what happened, who did it, on which device."
        },
        "notice": {
          "type": "string",
          "description": "After an action: something to read, eg a refund that did not go through."
        },
        "repeated": {
          "type": "boolean",
          "description": "POST /shop/orders: true = this key was used before and this is that order."
        },
        "checkout_url": {
          "type": "string",
          "description": "POST /shop/orders with pay online: where the customer pays."
        },
        "payment_id": {
          "type": "integer",
          "nullable": true
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopOrderActionRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "action": {
          "type": "string",
          "enum": [
            "accept",
            "preparing",
            "ready",
            "out_for_delivery",
            "complete",
            "cancel",
            "reject",
            "time",
            "no_show",
            "hand_lines"
          ]
        },
        "reason": {
          "type": "string",
          "description": "cancel, reject: what the customer is told."
        },
        "minutes": {
          "type": "integer",
          "description": "time: minutes later (negative: earlier)."
        },
        "refund": {
          "type": "boolean",
          "description": "cancel, reject of a paid order: refund it. no_show: refund what was paid online (default false: the payment is kept)."
        },
        "restock": {
          "type": "boolean",
          "description": "cancel, reject: give the stock back (default true). no_show: default false."
        },
        "collected": {
          "type": "string",
          "enum": [
            "cash",
            "card"
          ],
          "description": "complete of an order paid at the counter."
        },
        "lines": {
          "type": "array",
          "description": "hand_lines: the lines given now (the shop setting orders.partial_handover must be on). The order stays open; complete hands over what is left.",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "qty": {
                "type": "integer",
                "minimum": 1,
                "description": "How many of this line. Left out: all that is left of it."
              }
            },
            "required": [
              "id"
            ]
          }
        }
      },
      "required": [
        "action"
      ]
    },
    "ShopRefundRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "amount": {
          "type": "integer",
          "minimum": 1,
          "description": "Minor units. Left out: all that is left."
        }
      }
    },
    "ShopQuoteRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "lines": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "item_id": {
                "type": "integer"
              },
              "qty": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              },
              "variant_id": {
                "type": "integer",
                "nullable": true,
                "description": "Needed for an item with variants."
              },
              "option_ids": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "description": "Choices from the item's option groups."
              },
              "note": {
                "type": "string",
                "maxLength": 200
              }
            },
            "required": [
              "item_id"
            ]
          },
          "minItems": 1
        },
        "fulfilment": {
          "type": "string",
          "enum": [
            "pickup",
            "delivery"
          ],
          "default": "pickup"
        },
        "address": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "line1": {
              "type": "string",
              "description": "Street and number."
            },
            "line2": {
              "type": "string"
            },
            "suburb": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "notes": {
              "type": "string",
              "description": "For the driver."
            },
            "lat": {
              "type": "number",
              "description": "Where the customer is (latitude), with lng. Only the delivery options that charge by distance read it; without it they answer code `location`."
            },
            "lng": {
              "type": "number",
              "description": "Longitude, with lat."
            }
          },
          "description": "Needed for delivery: line1 and at least one of suburb, city or postcode."
        },
        "delivery_method": {
          "type": "string",
          "description": "When the shop has several delivery options: the id of one (GET /shop/settings, config.delivery.methods)."
        },
        "discount_code": {
          "type": "string"
        },
        "tip_percent": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "tip_minor": {
          "type": "integer",
          "minimum": 0,
          "description": "A tip as an amount; wins over tip_percent."
        },
        "contact": {
          "type": "string",
          "description": "Optional: the customer's WhatsApp number, for discount codes that depend on the customer."
        }
      },
      "required": [
        "lines"
      ]
    },
    "ShopQuoteResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "quote": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "currency": {
              "type": "string"
            },
            "lines": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "items_count": {
              "type": "integer"
            },
            "subtotal": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "discount": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "discount_code": {
              "type": "string"
            },
            "discount_message": {
              "type": "string"
            },
            "fulfilment": {
              "type": "string"
            },
            "delivery_fee": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "delivery_method": {
              "type": "string"
            },
            "delivery_zone": {
              "type": "string"
            },
            "fees_total": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "tip": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "tax": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "tax_included": {
              "type": "boolean"
            },
            "total": {
              "type": "integer",
              "description": "Whole minor units (cents): 1250 = 12.50."
            },
            "total_label": {
              "type": "string"
            },
            "prep_minutes": {
              "type": "integer"
            },
            "ok": {
              "type": "boolean",
              "description": "true = nothing is in the way."
            },
            "problems": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "unavailable, sold_out, choose_variant, option_min, option_max, option_sold_out, min_qty, max_qty, stock, min_order, discount, fulfilment, delivery_method, delivery_area or delivery_min_order."
                  },
                  "message": {
                    "type": "string"
                  },
                  "line": {
                    "type": "integer",
                    "description": "The index of the line in your request; -1 = the whole order."
                  },
                  "left": {
                    "type": "integer",
                    "description": "For stock: how many can be had."
                  }
                }
              }
            }
          },
          "description": "The cart priced from the shop's data as it is now."
        },
        "times": {
          "type": "object",
          "additionalProperties": true,
          "description": "asap { offered, ok, ready_label, ready_at, message }, slots_on, days [{ date, label, slots [{ start, label, full }] }], open_now, paused."
        },
        "pay": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "online": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "The connected ways to pay online (stripe, paypal)."
            },
            "later": {
              "type": "boolean"
            },
            "must_prepay": {
              "type": "boolean"
            },
            "free": {
              "type": "boolean"
            }
          }
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopOrderCreateRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "lines": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "item_id": {
                "type": "integer"
              },
              "qty": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              },
              "variant_id": {
                "type": "integer",
                "nullable": true,
                "description": "Needed for an item with variants."
              },
              "option_ids": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "description": "Choices from the item's option groups."
              },
              "note": {
                "type": "string",
                "maxLength": 200
              }
            },
            "required": [
              "item_id"
            ]
          },
          "minItems": 1
        },
        "fulfilment": {
          "type": "string",
          "enum": [
            "pickup",
            "delivery"
          ],
          "default": "pickup"
        },
        "address": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "line1": {
              "type": "string",
              "description": "Street and number."
            },
            "line2": {
              "type": "string"
            },
            "suburb": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "notes": {
              "type": "string",
              "description": "For the driver."
            },
            "lat": {
              "type": "number",
              "description": "Where the customer is (latitude), with lng. Only the delivery options that charge by distance read it; without it they answer code `location`."
            },
            "lng": {
              "type": "number",
              "description": "Longitude, with lat."
            }
          },
          "description": "Needed for delivery: line1 and at least one of suburb, city or postcode."
        },
        "delivery_method": {
          "type": "string",
          "description": "When the shop has several delivery options: the id of one (GET /shop/settings, config.delivery.methods)."
        },
        "discount_code": {
          "type": "string"
        },
        "tip_percent": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "tip_minor": {
          "type": "integer",
          "minimum": 0,
          "description": "A tip as an amount; wins over tip_percent."
        },
        "contact": {
          "type": "string",
          "description": "The customer's WhatsApp number with the country code, digits only."
        },
        "name": {
          "type": "string",
          "minLength": 2
        },
        "email": {
          "type": "string"
        },
        "asap": {
          "type": "boolean",
          "default": true
        },
        "slot": {
          "type": "string",
          "description": "With asap false: the start of a time the quote offered, YYYY-MM-DDTHH:mm in the shop's time.",
          "example": "2026-11-14T18:30"
        },
        "note": {
          "type": "string"
        },
        "allergy_note": {
          "type": "string"
        },
        "pay": {
          "type": "string",
          "enum": [
            "later",
            "online"
          ],
          "default": "later"
        },
        "method": {
          "type": "string",
          "description": "With pay online: stripe or paypal; empty = the first connected."
        },
        "expected_total": {
          "type": "integer",
          "description": "The total the customer agreed to: a different total answers 409 shop_changed with the new quote."
        },
        "client_key": {
          "type": "string",
          "maxLength": 70,
          "description": "Your own unique key of this order (the Idempotency-Key header does the same): the same key again answers the same order."
        }
      },
      "required": [
        "contact",
        "name",
        "lines"
      ]
    },
    "ShopReportResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "report": {
          "type": "object",
          "additionalProperties": true,
          "description": "orders (counts by state), money (sales, paid online, at the counter by cash and card, delivery fees, tips, discounts, tax, refunds), items (best sellers), hours, hand-overs, per day, top customers, codes, sources; from, to, timezone."
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "ShopLinkRequest": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "contact": {
          "type": "string",
          "description": "The customer's WhatsApp number with the country code, digits only.",
          "example": "61412345678"
        }
      },
      "required": [
        "contact"
      ]
    },
    "ShopLinkResponse": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "success": {
          "type": "boolean",
          "example": true
        },
        "request_id": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "page_url": {
          "type": "string"
        },
        "days": {
          "type": "integer"
        },
        "enabled": {
          "type": "boolean"
        }
      },
      "required": [
        "success",
        "request_id"
      ]
    },
    "SubmitProblem": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "example": "definition.steps[1].fields[2].pattern",
          "description": "Where in the body that was sent."
        },
        "code": {
          "type": "string",
          "example": "bad_pattern",
          "description": "A short word for the kind of problem (required, too_long, duplicate_key, reserved_key, unknown_type, unknown_field, rule_later_field, unknown_list, word_taken, too_many, bad_pattern, bad_formula, bad_stage, needs_open_and_done ...)."
        },
        "message": {
          "type": "string",
          "description": "What is wrong."
        },
        "fix": {
          "type": "string",
          "description": "What to change."
        }
      },
      "description": "One problem of a checked document. A 400 answer (invalid_form, invalid_automation, invalid_setup ...) carries the list in error.details; a dry run of POST /submit/setup carries it in problems."
    },
    "SubmitRule": {
      "type": "object",
      "additionalProperties": true,
      "description": "A rule is {\"field\": \"<key>\", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {\"all\": [rule, ...]} (every one) or {\"any\": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {\"field\": \"deliver\", \"equals\": true}; {\"all\": [{\"field\": \"amount\", \"gt\": 5000}, {\"field\": \"category\", \"in\": [\"plant\", \"vehicle\"]}]}. In a form (show_if) the field must belong to an EARLIER step. `equals`: The value is this. `not_equals`: The value is not this. `in`: The value is one of these (an array). `not_in`: The value is none of these (an array). `contains`: The text contains this (case does not matter), or the array has this item. `empty`: true: there is no value. `not_empty`: true: there is a value. `gt`: Greater than (numbers, dates). `gte`: Greater than or equal. `lt`: Less than. `lte`: Less than or equal.",
      "properties": {
        "field": {
          "type": "string",
          "example": "amount",
          "description": "A field key (or an extra key). Automations may also name status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone."
        },
        "equals": {},
        "not_equals": {},
        "in": {
          "type": "array",
          "items": {}
        },
        "not_in": {
          "type": "array",
          "items": {}
        },
        "contains": {},
        "empty": {
          "type": "boolean"
        },
        "not_empty": {
          "type": "boolean"
        },
        "gt": {},
        "gte": {},
        "lt": {},
        "lte": {},
        "all": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "A group: every rule in it must hold."
        },
        "any": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "A group: at least one rule in it must hold."
        }
      },
      "example": {
        "all": [
          {
            "field": "amount",
            "gt": 5000
          },
          {
            "field": "category",
            "in": [
              "plant",
              "vehicle"
            ]
          }
        ]
      }
    },
    "SubmitFormField": {
      "type": "object",
      "required": [
        "key",
        "type",
        "label"
      ],
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]{0,39}$",
          "example": "reading",
          "description": "The field's name in answers, rules, placeholders, formulas and exports: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique in the form, not a reserved word, not starting with _. Reserved: reference, status, status_name, form, form_key, channel, contact, link, id, created, updated, assignee, priority, tags, due, files, flow_token, screen, error_message, error, answers, extra, submission, note, button, business, desk_link, status_kind, verified, files_count, prefill, confirm, true, false, null, and, or, not."
        },
        "type": {
          "type": "string",
          "enum": [
            "text",
            "textarea",
            "number",
            "email",
            "phone",
            "date",
            "select",
            "multiselect",
            "yesno",
            "rating",
            "consent",
            "photo",
            "document",
            "location",
            "info",
            "hidden"
          ],
          "description": "The field type decides the answer's JSON type, the keys that apply and how WhatsApp shows it. `text` (value: string; on WhatsApp: text input): min_length, max_length, pattern. `textarea` (value: string; on WhatsApp: text area): min_length, max_length, pattern. `number` (value: number; on WhatsApp: number input): min, max, decimals, unit. `email` (value: string; on WhatsApp: e-mail input). `phone` (value: string; on WhatsApp: phone input). 6 to 20 digits. `date` (value: string, YYYY-MM-DD; on WhatsApp: date picker): min_days, max_days. `select` (value: string: the id of the choice; on WhatsApp: radio buttons up to 8 choices, a dropdown above that): choices, list. While its list is empty a select is not required and not checked. `multiselect` (value: array of strings: the ids of the choices; on WhatsApp: checkboxes): choices, min_choices, max_choices. `yesno` (value: boolean; on WhatsApp: Yes / No radio buttons). `rating` (value: number, 1 to max; on WhatsApp: radio buttons 1 to max): max. `consent` (value: boolean; on WhatsApp: a tick box). The label is the sentence to agree to (at most 120 characters). required true = it must be ticked. `photo` (value: array of file ids; on WhatsApp: photo picker): max_files, source. WhatsApp allows one photo or document picker on a screen: a step with several is split into several screens by itself. `document` (value: array of file ids; on WhatsApp: document picker): max_files, kinds. One picker on a screen, as for photo. `location` (value: string: the address text; the pin is the submission's location {lat, lng, name, address}; on WhatsApp: asked after the form with WhatsApp's own Send location request). On the web page: a Use my location button and an address line. One location field in a form; required is not enforced for it. `info` (value: nothing is stored; on WhatsApp: a heading (the label) and text): text. `hidden` (value: string; on WhatsApp: nothing is shown). The value is the field's default (usually {prefill.<key>}), or the prefill value given under the field's own key: a job number or an account that arrives with the link or the send call."
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "example": "Meter reading",
          "description": "The question, 1 to 200 characters. A label longer than WhatsApp allows on the input is moved into text above it by itself."
        },
        "help": {
          "type": "string",
          "maxLength": 80,
          "description": "A hint with the input, up to 80 characters."
        },
        "required": {
          "type": "boolean",
          "description": "true: must be answered (consent: must be ticked). Default false. Not enforced for a location field: the pin arrives after the form."
        },
        "internal": {
          "type": "boolean",
          "default": false,
          "description": "true: never asked. Staff, the API or an automation fill it (a quote amount, a decision reason, an id another system returned). Its value is stored in the submission's extra and shows in the inbox and in exports. Only for the types text, textarea, number, email, phone, date, select, multiselect, yesno and rating; an internal field is never required and has no show_if. Default false."
        },
        "show_if": {
          "$ref": "#/definitions/SubmitRule",
          "nullable": true,
          "description": "A rule on fields of EARLIER steps: the field is asked only when the rule holds. The rule may look at fields that are asked or hidden, not at internal or info fields. A field that is not shown counts as empty for the rules after it. null = always."
        },
        "default": {
          "type": "string",
          "description": "The starting value, up to 500 characters: a literal, or the placeholders {contact.name}, {contact.phone}, {contact.<custom field>}, {prefill.<key>} (prefill = the values given when the form is sent). Not for photo, document, location and info."
        },
        "sensitive": {
          "type": "boolean",
          "default": false,
          "description": "true: the value is masked in WhatsApp's own summary of the form. Only for the types text, textarea, number, email, phone, date, select, multiselect, yesno and rating. Default false."
        },
        "min_length": {
          "type": "integer",
          "minimum": 0,
          "description": "text, textarea. Fewest characters. 0 = none."
        },
        "max_length": {
          "type": "integer",
          "minimum": 0,
          "description": "text, textarea. Most characters. 0 = the type's limit (text 200, textarea 2,000)."
        },
        "pattern": {
          "type": "string",
          "maxLength": 200,
          "description": "text, textarea. A regular expression the whole answer must match, up to 200 characters."
        },
        "min": {
          "type": "number",
          "nullable": true,
          "description": "number. Smallest value. null = none."
        },
        "max": {
          "type": "number",
          "nullable": true,
          "description": "number: the largest value, null = none. rating: the highest rating, 3 to 10, default 5."
        },
        "decimals": {
          "type": "integer",
          "minimum": 0,
          "maximum": 6,
          "default": 0,
          "description": "number. Decimal places allowed, 0 to 6. Default 0."
        },
        "unit": {
          "type": "string",
          "example": "kWh",
          "description": "number. Shown after the value, for example kWh. Up to 20 characters."
        },
        "min_days": {
          "type": "integer",
          "nullable": true,
          "description": "date. Earliest day, counted from today (negative = in the past). null = none."
        },
        "max_days": {
          "type": "integer",
          "nullable": true,
          "description": "date. Latest day, counted from today. null = none."
        },
        "choices": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "maxLength": 40,
                "example": "gas",
                "description": "What is stored as the answer. Unique in the field."
              },
              "title": {
                "type": "string",
                "maxLength": 80,
                "example": "Gas",
                "description": "What people see (WhatsApp shows the first 30 characters)."
              },
              "description": {
                "type": "string",
                "maxLength": 300,
                "description": "A second line, optional."
              }
            },
            "required": [
              "id",
              "title"
            ]
          },
          "description": "select: 2 to 200 choices (or use list). multiselect: 2 to 20 choices."
        },
        "list": {
          "type": "string",
          "example": "products",
          "description": "select. Instead of choices: the key of a list of the number (GET /submit/lists). The list is read each time the form opens, so changing it needs no publish. At most 200 items are shown."
        },
        "min_choices": {
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "description": "multiselect. Fewest ticks. 0 = none."
        },
        "max_choices": {
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "description": "multiselect. Most ticks. 0 = no limit."
        },
        "max_files": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "default": 1,
          "description": "photo, document. How many files, 1 to 10."
        },
        "source": {
          "type": "string",
          "enum": [
            "any",
            "camera",
            "gallery"
          ],
          "default": "any",
          "description": "photo. Where the photo may come from."
        },
        "kinds": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "any",
              "pdf",
              "image",
              "office"
            ]
          },
          "description": "document. What may be sent: [\"any\"] (default), or some of pdf, image, office."
        },
        "text": {
          "type": "string",
          "maxLength": 1000,
          "description": "info. The text shown, up to 1,000 characters."
        }
      },
      "description": "One question, or one value that is carried along. Every type takes key, type, label, help, required, internal, show_if, default and sensitive; the other keys belong to one or two types and a key that does not apply is dropped when the form is saved.",
      "example": {
        "key": "reading",
        "type": "number",
        "label": "Meter reading",
        "required": true,
        "min": 0,
        "max": 999999,
        "decimals": 0,
        "unit": "kWh"
      }
    },
    "SubmitFormStep": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]{0,39}$",
          "example": "reading",
          "description": "The step's name: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique among the steps."
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60,
          "example": "Your reading",
          "description": "The screen's title, 1 to 60 characters (WhatsApp shows the first 30)."
        },
        "text": {
          "type": "string",
          "maxLength": 500,
          "description": "Shown above the fields, up to 500 characters."
        },
        "show_if": {
          "$ref": "#/definitions/SubmitRule",
          "nullable": true,
          "description": "A rule on fields of EARLIER steps: the step is skipped when it does not hold. null = always."
        },
        "fields": {
          "type": "array",
          "minItems": 1,
          "maxItems": 12,
          "items": {
            "$ref": "#/definitions/SubmitFormField"
          },
          "description": "1 to 12 fields. Internal and hidden fields count but show nothing."
        }
      },
      "required": [
        "key",
        "title",
        "fields"
      ],
      "description": "One step of a form: a title and its fields."
    },
    "SubmitFormStage": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]{0,39}$",
          "example": "received",
          "description": "The stage's name in the API (the submission's status): a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique in the form."
        },
        "name": {
          "type": "string",
          "example": "Received",
          "description": "What people see, for example In review. Up to 40 characters."
        },
        "kind": {
          "type": "string",
          "enum": [
            "open",
            "done",
            "cancelled"
          ],
          "description": "open: still being worked on. done: finished well. cancelled: finished without a result. A form needs at least one open and one done stage."
        },
        "color": {
          "type": "string",
          "enum": [
            "grey",
            "blue",
            "green",
            "amber",
            "red",
            "purple"
          ],
          "description": "grey, blue, green, amber, red or purple."
        },
        "set_by": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "agent",
              "viewer"
            ]
          },
          "description": "The roles that may choose this stage: some of owner, admin, manager, agent, viewer. [] = anyone who may change stages. Owners, admins, automations and API keys always may."
        },
        "require_note": {
          "type": "boolean",
          "description": "true: a note must come with the move to this stage."
        },
        "message": {
          "type": "string",
          "maxLength": 1000,
          "description": "Sent to the submitter when the submission arrives in this stage, up to 1,000 characters, with placeholders ({note} = the note of the change). \"\" = nothing is sent."
        }
      },
      "required": [
        "key",
        "name",
        "kind"
      ],
      "description": "A stage of a form. Inside a submission the stages come without message."
    },
    "SubmitFormDefinition": {
      "type": "object",
      "required": [
        "title",
        "steps"
      ],
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60,
          "example": "Meter reading",
          "description": "The form's public name, 1 to 60 characters."
        },
        "description": {
          "type": "string",
          "maxLength": 300,
          "description": "Under the title on the web page and in the forms menu, up to 300 characters."
        },
        "prefix": {
          "type": "string",
          "example": "MR",
          "description": "2 to 4 letters A-Z that start every reference of this form (MR-7Q3M2A). \"\" = the settings' default_prefix."
        },
        "steps": {
          "type": "array",
          "minItems": 1,
          "maxItems": 12,
          "items": {
            "$ref": "#/definitions/SubmitFormStep"
          },
          "description": "1 to 12 steps, in the order they are asked. One step is one screen; app2email splits a step over several screens by itself when WhatsApp's limits demand it."
        },
        "stages": {
          "type": "array",
          "minItems": 2,
          "maxItems": 12,
          "items": {
            "$ref": "#/definitions/SubmitFormStage"
          },
          "description": "2 to 12 stages a submission moves through. The first one is where a new submission starts. At least one of kind open and one of kind done. Left out: New (open), In progress (open), Done (done)."
        },
        "who": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "anyone",
                "listed"
              ],
              "default": "anyone",
              "description": "listed: only the numbers below, or contacts with the tag, may submit (a form for field staff). listed needs at least one number or a tag."
            },
            "numbers": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Up to 500 numbers, digits only with country code (6 to 20 digits)."
            },
            "tag": {
              "type": "string",
              "maxLength": 40,
              "description": "A contact tag: contacts carrying it may submit."
            }
          },
          "description": "Who may submit."
        },
        "trigger": {
          "type": "object",
          "properties": {
            "words": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 10,
              "example": [
                "meter"
              ],
              "description": "A contact who sends one of these words gets the form. Up to 10 words, 30 characters each. A word that another form of the number or an enabled Book-and-Pay word already uses is refused (word_taken)."
            },
            "header": {
              "type": "string",
              "maxLength": 60,
              "description": "A bold line above the body, optional."
            },
            "body": {
              "type": "string",
              "maxLength": 1000,
              "example": "Tap the button to send your reading.",
              "description": "The text of the message that carries the form, 1 to 1,000 characters. Left out: Tap the button to open the form."
            },
            "button": {
              "type": "string",
              "maxLength": 20,
              "example": "Open form",
              "description": "The button's text, 1 to 20 characters. Left out: Open form."
            },
            "footer": {
              "type": "string",
              "maxLength": 60,
              "description": "A small grey line, optional."
            }
          },
          "description": "The message that opens the form on WhatsApp, and the words that send it."
        },
        "after": {
          "type": "object",
          "properties": {
            "review_step": {
              "type": "boolean",
              "default": true,
              "description": "A last screen that lists the answers before sending."
            },
            "reply": {
              "type": "string",
              "maxLength": 1000,
              "description": "The WhatsApp message after sending, with placeholders ({reference}, {form}, {contact.name} ...). \"\" = no reply. Left out: a thank-you with the reference."
            },
            "allow_additions": {
              "type": "boolean",
              "default": false,
              "description": "The reply gets an Add more button: text, photos and files the submitter sends in the next 10 minutes are attached to the submission."
            },
            "status_page": {
              "type": "boolean",
              "default": true,
              "description": "The reply carries a button to the submitter's status page."
            }
          },
          "description": "What happens right after a submission."
        },
        "web": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": true,
              "description": "The form has a web page (links.web of the form)."
            },
            "verify": {
              "type": "string",
              "enum": [
                "off",
                "optional",
                "required"
              ],
              "default": "optional",
              "description": "Proving the WhatsApp number of a web submission with one message. optional: offered as Get updates on WhatsApp. required: the submission counts only once proven. off: never asked."
            },
            "ask_email": {
              "type": "boolean",
              "default": false,
              "description": "Also ask for an e-mail address at the end."
            },
            "success_text": {
              "type": "string",
              "maxLength": 500,
              "description": "Shown after sending. \"\" = the standard text."
            }
          },
          "description": "The web page of the form."
        },
        "notify": {
          "type": "object",
          "properties": {
            "email": {
              "type": "boolean",
              "default": true,
              "description": "E-mail the business for each submission (to the settings' notify_email)."
            },
            "to": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 5,
              "description": "Up to 5 more addresses."
            },
            "attach_files": {
              "type": "boolean",
              "default": true,
              "description": "Attach the submission's files."
            }
          },
          "description": "The e-mail the business gets."
        },
        "calculated": {
          "type": "array",
          "maxItems": 20,
          "description": "0 to 20 calculated fields: values worked out from the answers each time they change, stored in extra. Formulas (calculated fields, the calculate action, and {= ... } inside any text): numbers, 'texts' in single quotes, field keys, + - * / %, the comparisons == != > >= < <=, and / or / not, brackets, and the functions if(condition, then, else): then when the condition holds, otherwise else (null without an else). min(a, b, ...): The smallest number. max(a, b, ...): The largest number. round(x, decimals): x rounded, half away from zero; decimals 0 to 10, default 0. abs(x): x without its sign. num(x): x as a number, null when it is not one. len(x): The length of a text, or the number of items of a list. coalesce(a, b, ...): The first value that is not empty. lower(x): x in lower case. upper(x): x in upper case. concat(a, b, ...): The values joined as one text. lookup('<list>', id, '<column>'): A column of the item with that id in a list of the number, for example a price. previous('<field>'): The same contact's last value of that field in this form. count_files('<field>'): How many files a photo or document field holds. days_since(date): Whole days from a date (YYYY-MM-DD) to today; negative for a date to come. No loops and no assignment; at most 500 characters; a division by zero or a missing number gives null. Examples: reading - previous('reading'); quantity * lookup('products', product, 'price'); if(usage < 0, 'check', 'ok'); round(amount * 1.2, 2); days_since(purchase_date) > 30 and count_files('receipt') == 0.",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "example": "usage",
                "description": "Its name in extra, rules and placeholders. Same rules as a field key."
              },
              "label": {
                "type": "string",
                "maxLength": 60,
                "example": "Usage"
              },
              "formula": {
                "type": "string",
                "maxLength": 500,
                "example": "reading - previous('reading')"
              },
              "unit": {
                "type": "string"
              },
              "decimals": {
                "type": "integer",
                "minimum": 0,
                "maximum": 6
              }
            },
            "required": [
              "key",
              "formula"
            ]
          }
        },
        "retention_days": {
          "type": "integer",
          "default": 0,
          "description": "0 = keep. Otherwise closed submissions and their files are erased this many days after closing (30 to 3650)."
        }
      },
      "example": {
        "title": "Meter reading",
        "description": "Send us this month's reading.",
        "prefix": "MR",
        "steps": [
          {
            "key": "reading",
            "title": "Your reading",
            "text": "",
            "show_if": null,
            "fields": [
              {
                "key": "meter_no",
                "type": "text",
                "label": "Meter number",
                "help": "On the front of the meter",
                "required": true,
                "default": "{contact.meter_no}",
                "max_length": 20
              },
              {
                "key": "reading",
                "type": "number",
                "label": "Meter reading",
                "required": true,
                "min": 0,
                "max": 999999,
                "decimals": 0,
                "unit": "kWh"
              },
              {
                "key": "photo",
                "type": "photo",
                "label": "Photo of the meter",
                "required": true,
                "max_files": 1,
                "source": "camera"
              },
              {
                "key": "moving",
                "type": "yesno",
                "label": "Are you moving out?",
                "required": true
              },
              {
                "key": "billing_ref",
                "type": "text",
                "label": "Billing reference",
                "internal": true
              }
            ]
          },
          {
            "key": "move",
            "title": "Your move",
            "text": "We will close the account on that day.",
            "show_if": {
              "field": "moving",
              "equals": true
            },
            "fields": [
              {
                "key": "move_date",
                "type": "date",
                "label": "Moving date",
                "required": true,
                "min_days": -30,
                "max_days": 90
              },
              {
                "key": "new_address",
                "type": "textarea",
                "label": "New address for the final bill",
                "required": false,
                "max_length": 300
              }
            ]
          }
        ],
        "stages": [
          {
            "key": "received",
            "name": "Received",
            "kind": "open",
            "color": "blue",
            "set_by": [],
            "require_note": false,
            "message": ""
          },
          {
            "key": "queried",
            "name": "Queried",
            "kind": "open",
            "color": "amber",
            "set_by": [],
            "require_note": true,
            "message": "We have a question about your reading {reference}: {note}"
          },
          {
            "key": "checked",
            "name": "Checked",
            "kind": "done",
            "color": "green",
            "set_by": [
              "manager"
            ],
            "require_note": false,
            "message": "Thanks {contact.name}, your reading of {reading} kWh is recorded."
          }
        ],
        "who": {
          "mode": "anyone",
          "numbers": [],
          "tag": ""
        },
        "trigger": {
          "words": [
            "meter",
            "reading"
          ],
          "header": "",
          "body": "Tap the button to send your reading.",
          "button": "Open form",
          "footer": ""
        },
        "after": {
          "review_step": true,
          "reply": "Thanks {contact.name}. We have your {form} - reference {reference}.",
          "allow_additions": false,
          "status_page": true
        },
        "web": {
          "enabled": true,
          "verify": "optional",
          "ask_email": false,
          "success_text": ""
        },
        "notify": {
          "email": true,
          "to": [],
          "attach_files": true
        },
        "calculated": [
          {
            "key": "usage",
            "label": "Usage",
            "formula": "reading - previous('reading')",
            "unit": "kWh",
            "decimals": 0
          }
        ],
        "retention_days": 0
      },
      "description": "A form as one document. The same JSON drives the WhatsApp form (app2email generates it: there is nothing to draw), the web page, the checks on every answer, the inbox columns and the exports. `steps` hold the fields; `stages` are the states a submission moves through; `who`, `trigger`, `after`, `web`, `notify`, `calculated` and `retention_days` are optional and take their defaults when left out. Limits: 12 steps, 12 fields in a step, 60 fields in a form, one location field, 64 KB of JSON. A save is checked as a whole: with any problem nothing is saved and the 400 answer lists each one with its path and a fix. The saved form comes back normalized, with every default filled in. Saving changes the working copy; WhatsApp keeps showing the published version until POST /submit/forms/{key}/publish is called again. Conditions: a step or a field with `show_if` appears only when its rule holds, and the rule may only look at fields of earlier steps. A rule is {\"field\": \"<key>\", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {\"all\": [rule, ...]} (every one) or {\"any\": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {\"field\": \"deliver\", \"equals\": true}; {\"all\": [{\"field\": \"amount\", \"gt\": 5000}, {\"field\": \"category\", \"in\": [\"plant\", \"vehicle\"]}]}."
    },
    "SubmitFieldInfo": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "text",
            "textarea",
            "number",
            "email",
            "phone",
            "date",
            "select",
            "multiselect",
            "yesno",
            "rating",
            "consent",
            "photo",
            "document",
            "location",
            "info",
            "hidden"
          ]
        },
        "step": {
          "type": "string",
          "description": "The key of its step. Empty for a calculated field."
        },
        "internal": {
          "type": "boolean",
          "description": "true: its value is in extra, not in answers."
        },
        "unit": {
          "type": "string"
        },
        "choices": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "maxLength": 40,
                "example": "gas",
                "description": "What is stored as the answer. Unique in the field."
              },
              "title": {
                "type": "string",
                "maxLength": 80,
                "example": "Gas",
                "description": "What people see (WhatsApp shows the first 30 characters)."
              },
              "description": {
                "type": "string",
                "maxLength": 300,
                "description": "A second line, optional."
              }
            },
            "required": [
              "id",
              "title"
            ]
          },
          "description": "select and multiselect."
        },
        "calculated": {
          "type": "boolean",
          "description": "true: worked out by a formula."
        }
      },
      "description": "One field of a form, as a column: the key to read in answers or extra, and how to label it."
    },
    "SubmitForm": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "example": 7
        },
        "key": {
          "type": "string",
          "example": "meter_reading",
          "description": "The form's name in the API and in its web address."
        },
        "name": {
          "type": "string",
          "example": "Meter reading"
        },
        "enabled": {
          "type": "boolean",
          "description": "false: its words and links answer nothing new; its submissions stay."
        },
        "archived": {
          "type": "boolean",
          "description": "true: hidden from the lists, takes no submissions."
        },
        "position": {
          "type": "integer"
        },
        "definition": {
          "$ref": "#/definitions/SubmitFormDefinition",
          "description": "The working copy. One form only."
        },
        "published": {
          "type": "object",
          "nullable": true,
          "description": "The version live on WhatsApp, or null when it was never published.",
          "properties": {
            "hash": {
              "type": "string",
              "example": "3f9a1c0b7d2e"
            },
            "published_at": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "changed": {
          "type": "boolean",
          "description": "true: the working copy differs from the published version: publish to make it live on WhatsApp. false also while the form was never published (published is null then)."
        },
        "flow": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Meta's id of the WhatsApp Flow. Empty until published."
            },
            "status": {
              "type": "string",
              "enum": [
                "",
                "DRAFT",
                "PUBLISHED",
                "DEPRECATED",
                "BLOCKED",
                "THROTTLED"
              ],
              "description": "Meta's status. Only PUBLISHED is sent to customers."
            },
            "validation_errors": {
              "type": "array",
              "items": {},
              "description": "Meta's complaints about the generated form, when there are any."
            },
            "checked_at": {
              "type": "string",
              "description": "When the status was last read from Meta. Empty: never."
            },
            "last_error": {
              "type": "string",
              "description": "Why the last publish failed. Empty when it worked."
            },
            "can_send": {
              "type": "boolean",
              "description": "true: the form can be sent inside WhatsApp now. false: its words and the send route answer with the web link."
            }
          },
          "description": "The form's state on WhatsApp."
        },
        "links": {
          "type": "object",
          "properties": {
            "web": {
              "type": "string",
              "description": "The web page of the form."
            },
            "wa_me": {
              "type": "string",
              "description": "Opens the WhatsApp chat with the form's first word typed in. Put it behind a link or a QR code."
            },
            "words": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "description": "How people reach the form."
        },
        "counts": {
          "type": "object",
          "properties": {
            "open": {
              "type": "integer"
            },
            "total": {
              "type": "integer"
            }
          },
          "description": "Its submissions."
        },
        "fields": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitFieldInfo"
          },
          "description": "Every field and calculated value as a column. One form only."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "A form. GET /submit/forms lists forms without definition and fields; GET /submit/forms/{key} has both."
    },
    "SubmitListItem": {
      "type": "object",
      "required": [
        "id",
        "title"
      ],
      "additionalProperties": true,
      "description": "One choice. Any other key is a column that formulas read with lookup('<list>', id, '<column>'), for example price. PUT also takes a plain text as an item: it becomes the id and the title.",
      "properties": {
        "id": {
          "type": "string",
          "example": "pump-s",
          "description": "What is stored as the answer. Unique in the list."
        },
        "title": {
          "type": "string",
          "example": "Pump, small"
        },
        "description": {
          "type": "string"
        }
      }
    },
    "SubmitList": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "example": "products"
        },
        "name": {
          "type": "string",
          "example": "Products"
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitListItem"
          }
        },
        "count": {
          "type": "integer"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "Choices kept outside the forms: sites, jobs, products with prices. A select field with list = this key shows them, read fresh each time the form opens."
    },
    "SubmissionFile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "example": 9917,
          "description": "What a photo or document answer holds."
        },
        "field": {
          "type": "string",
          "description": "The field it belongs to. Empty: added afterwards."
        },
        "name": {
          "type": "string"
        },
        "mime": {
          "type": "string"
        },
        "size": {
          "type": "integer",
          "description": "Bytes."
        },
        "state": {
          "type": "string",
          "enum": [
            "pending",
            "stored",
            "failed"
          ],
          "description": "pending: still being fetched from WhatsApp. failed: could not be fetched."
        },
        "source": {
          "type": "string",
          "enum": [
            "flow",
            "web",
            "chat",
            "staff",
            "api"
          ],
          "description": "flow: the WhatsApp form. chat: sent in the chat afterwards."
        },
        "url": {
          "type": "string",
          "description": "Fetches the file's bytes without a key. Valid for 7 days from this answer; read the submission again for a fresh one. Empty until the file is stored."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "A file of a submission."
    },
    "SubmissionEvent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "kind": {
          "type": "string",
          "enum": [
            "created",
            "edited",
            "status",
            "assigned",
            "priority",
            "tags",
            "due",
            "note",
            "reply_out",
            "reply_in",
            "file",
            "location",
            "button",
            "automation",
            "followup",
            "viewed",
            "deleted",
            "restored",
            "error"
          ]
        },
        "actor": {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "system",
                "member",
                "contact",
                "api",
                "automation"
              ]
            },
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            }
          },
          "description": "Who did it."
        },
        "text": {
          "type": "string"
        },
        "data": {
          "type": "object",
          "additionalProperties": true,
          "description": "Details by kind, for example {from, to} of a stage change or {state: sent | held | email | failed} of a reply."
        },
        "public": {
          "type": "boolean",
          "description": "true: the submitter sees it on their status page."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "One line of a submission's activity list. The list only grows."
    },
    "Submission": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "example": 4182
        },
        "reference": {
          "type": "string",
          "example": "MR-7Q3M2A",
          "description": "The short code the submitter sees: the form's prefix and 6 characters. Every route that takes a submission id takes it too."
        },
        "form": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "description": "The form it was made with."
        },
        "channel": {
          "type": "string",
          "enum": [
            "whatsapp",
            "web",
            "api",
            "staff"
          ],
          "description": "whatsapp: the WhatsApp form. web: the web page. api: POST /submit/submissions. staff: entered by a team member."
        },
        "status": {
          "type": "string",
          "example": "received",
          "description": "The key of the stage it is in (the form's stages)."
        },
        "status_name": {
          "type": "string",
          "example": "Received"
        },
        "status_kind": {
          "type": "string",
          "enum": [
            "open",
            "done",
            "cancelled"
          ]
        },
        "status_color": {
          "type": "string",
          "enum": [
            "grey",
            "blue",
            "green",
            "amber",
            "red",
            "purple"
          ]
        },
        "priority": {
          "type": "string",
          "enum": [
            "low",
            "normal",
            "high",
            "urgent"
          ]
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "due": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "The due time, or null."
        },
        "assignee": {
          "type": "object",
          "nullable": true,
          "description": "The member it is assigned to, or null.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "contact": {
          "type": "object",
          "properties": {
            "identity": {
              "type": "string",
              "example": "61412345678",
              "description": "The submitter's WhatsApp number (digits, country code first) or business-scoped user id. Empty for a web submission with only an e-mail address."
            },
            "name": {
              "type": "string"
            },
            "phone": {
              "type": "string"
            },
            "email": {
              "type": "string"
            },
            "verified": {
              "type": "boolean",
              "description": "true: the number is proven (sent on WhatsApp, or confirmed from the web page with one message)."
            }
          }
        },
        "conversation_id": {
          "type": "integer",
          "description": "The WhatsApp conversation. 0 when there is none."
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "What was asked: field key -> value. The value's JSON type follows the field type (text: string, number and rating: number, yesno and consent: boolean, multiselect: array of choice ids, photo and document: array of file ids, date: YYYY-MM-DD, location: the address text)."
        },
        "extra": {
          "type": "object",
          "additionalProperties": true,
          "description": "Everything that was not asked: internal fields, calculated values and values automations saved."
        },
        "location": {
          "type": "object",
          "nullable": true,
          "description": "The pin the submitter sent, or null.",
          "properties": {
            "lat": {
              "type": "number"
            },
            "lng": {
              "type": "number"
            },
            "name": {
              "type": "string"
            },
            "address": {
              "type": "string"
            }
          }
        },
        "parent": {
          "type": "string",
          "nullable": true,
          "description": "The reference of the submission this one adds to (a follow-up form), or null."
        },
        "summary": {
          "type": "string",
          "description": "One line for lists: the first answers."
        },
        "files_count": {
          "type": "integer"
        },
        "files_pending": {
          "type": "integer",
          "description": "Files of the WhatsApp form that are still being fetched. 0 = all stored."
        },
        "unread": {
          "type": "boolean",
          "description": "New, or the submitter added something staff have not opened yet."
        },
        "link": {
          "type": "string",
          "description": "The submitter's own page: status, history, add information. No login; treat it as a secret of the submitter."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        },
        "status_changed": {
          "type": "string",
          "format": "date-time"
        },
        "closed": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When it reached a done or cancelled stage, or null."
        },
        "deleted": {
          "type": "string",
          "format": "date-time",
          "description": "Only on a deleted submission: when it was deleted."
        },
        "files": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmissionFile"
          },
          "description": "One submission only (and webhook events)."
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmissionEvent"
          },
          "description": "The activity list, oldest first. One submission only."
        },
        "fields": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitFieldInfo"
          },
          "description": "The form's fields, to label answers and extra. One submission only."
        },
        "stages": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitFormStage"
          },
          "description": "The stages it can move to. One submission only."
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "description": "The manual automations of its form: POST /submit/submissions/{id}/run with the id. One submission only."
        },
        "buttons": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            }
          },
          "description": "Buttons sent to the submitter that they have not pressed yet. One submission only (and webhook events)."
        }
      },
      "description": "What a person sent with a form, and everything that happened to it since. Lists carry the object up to closed; one submission (GET /submit/submissions/{id}) adds files, events, fields, stages, actions and buttons. The data of every submission.* webhook event is this object without events, fields, stages and actions."
    },
    "SubmitAction": {
      "type": "object",
      "required": [
        "type"
      ],
      "additionalProperties": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "set_status",
            "assign",
            "set_field",
            "calculate",
            "tag",
            "set_priority",
            "set_due",
            "reply",
            "ask_location",
            "send_form",
            "email",
            "notify",
            "http",
            "openapi",
            "mcp",
            "wait",
            "stop"
          ],
          "description": "What the action does. `set_status`: Move the submission to a stage. Keys: status, note. `assign`: Set the assignee. Keys: to. `set_field`: Store a value on the submission. Keys: key, value. `calculate`: Store the result of a formula. Keys: key, formula. `tag`: Add or remove tags. Keys: add, remove. `set_priority`: Set the priority. Keys: priority. `set_due`: Set the due time. Keys: minutes. `reply`: Message the submitter on WhatsApp (by e-mail when they gave only an e-mail address). Outside WhatsApp's reply window the message is held and announced like any reply from the Inbox. Keys: text, buttons, file, link. `ask_location`: Ask the submitter for their location with WhatsApp's Send location request. The pin is stored on the submission. Keys: text. `send_form`: Send another form as a follow-up. Its submission gets parent = this one, and customer_replied fires here when it arrives. Keys: form, text, prefill. `email`: Send an e-mail. Keys: to, subject, body, attach_files. `notify`: E-mail team members. Keys: to, text. `http`: Call an outside system with a plain HTTP request. Keys: connection, method, path, url, query, headers, body, save, on_fail. `openapi`: Call an operation of an imported OpenAPI document. Keys: connection, operation, params, body, save, on_fail. `mcp`: Call a tool of an MCP server. Keys: connection, tool, arguments, save, on_fail. `wait`: Pause. The rest runs later, and only if the conditions still hold then. Keys: minutes. `stop`: End the run here."
        },
        "status": {
          "type": "string",
          "description": "set_status. The stage key."
        },
        "note": {
          "type": "string",
          "description": "set_status. The note of the change (needed when the stage has require_note)."
        },
        "to": {
          "description": "assign: member:<id> = that member. role:<role> = the members with that role in turn (round robin). least_busy:<role> = the member with that role who has the fewest open submissions. none = nobody. email: A list of up to 10: owner, assignee, submitter, an address, or a placeholder that holds an address. notify: assignee, role:<role> or all."
        },
        "key": {
          "type": "string",
          "description": "set_field, calculate. An internal field of the form, or any other name that is not one of the form's questions and not a reserved word: it is stored in extra."
        },
        "value": {
          "description": "set_field. The value, with placeholders."
        },
        "formula": {
          "type": "string",
          "maxLength": 500,
          "description": "calculate. The formula (see the automation's description for the language)."
        },
        "add": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "tag. Tags to add."
        },
        "remove": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "tag. Tags to remove."
        },
        "priority": {
          "type": "string",
          "enum": [
            "low",
            "normal",
            "high",
            "urgent"
          ],
          "description": "set_priority."
        },
        "minutes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 525600,
          "description": "set_due: minutes from now, 0 to 525600 (0 takes the due time off). wait: how long to pause, 1 to 43200."
        },
        "text": {
          "type": "string",
          "description": "reply, ask_location, send_form, notify: the message, with placeholders."
        },
        "buttons": {
          "type": "array",
          "maxItems": 3,
          "description": "reply. 0 to 3 buttons: [{id (a-z, 0-9 and _, up to 20 characters, unique in the reply), title (up to 20 characters), set_status}]. Pressing one moves the submission to set_status (when given) and fires the button trigger.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "accept"
              },
              "title": {
                "type": "string",
                "maxLength": 20,
                "example": "Accept"
              },
              "set_status": {
                "type": "string",
                "example": "accepted",
                "description": "The stage the submission moves to when it is pressed. Left out: only the button trigger fires."
              }
            },
            "required": [
              "id",
              "title"
            ]
          }
        },
        "file": {
          "type": "string",
          "description": "reply. The key of a photo or document field whose files are sent along, or \"\"."
        },
        "link": {
          "type": "boolean",
          "description": "reply. true: add a button that opens the submitter's status page."
        },
        "form": {
          "type": "string",
          "description": "send_form. The key of the form to send."
        },
        "prefill": {
          "type": "object",
          "additionalProperties": true,
          "description": "send_form. Values for the new form: {\"<field key>\": value}, with placeholders. Up to 30 values."
        },
        "subject": {
          "type": "string",
          "description": "email."
        },
        "body": {
          "description": "email: the text. http, openapi: Any JSON; sent as application/json. A string that is exactly one placeholder keeps the value's type: \"{quantity}\" sends a number, \"{submission}\" the whole submission object."
        },
        "attach_files": {
          "type": "boolean",
          "description": "email. true: attach the submission's files (up to 15 MB in all; above that their links are listed). Default false."
        },
        "connection": {
          "type": "string",
          "description": "http, openapi, mcp. The connection's key (GET /submit/connections). http only: \"\" with a full url."
        },
        "method": {
          "type": "string",
          "enum": [
            "GET",
            "POST",
            "PUT",
            "PATCH",
            "DELETE"
          ],
          "description": "http."
        },
        "path": {
          "type": "string",
          "example": "/quotes",
          "description": "http. With a connection: added to its base address, for example /orders/{reference}. Each value a placeholder inserts is percent-encoded."
        },
        "url": {
          "type": "string",
          "description": "http. Without a connection: the full https address. Placeholders may stand in the path and the query, not in the host name."
        },
        "query": {
          "type": "object",
          "additionalProperties": true,
          "description": "http. Query parameters: {name: value}, up to 30."
        },
        "headers": {
          "type": "object",
          "additionalProperties": true,
          "description": "http. Extra headers: {name: value}, up to 10, each value up to 1,000 characters. Sign-in headers come from the connection only. Not allowed: Host, Content-Length, Transfer-Encoding, Connection, Cookie, Authorization, and names starting X-App2email-, Proxy-, X-Forwarded- or Content-."
        },
        "operation": {
          "type": "string",
          "example": "createTicket",
          "description": "openapi. A function id of the connection (GET /submit/connections/{key}/functions)."
        },
        "params": {
          "type": "object",
          "additionalProperties": true,
          "description": "openapi. The operation's parameters by name: {name: value}. Path, query and header parameters go where the document says; body parameters build the JSON body."
        },
        "tool": {
          "type": "string",
          "description": "mcp. The tool's name (GET /submit/connections/{key}/functions)."
        },
        "arguments": {
          "type": "object",
          "additionalProperties": true,
          "description": "mcp. The tool's arguments: {name: value}, typed like a JSON body."
        },
        "save": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "example": {
            "erp_id": "$.id",
            "quote_amount": "$.total"
          },
          "description": "http, openapi, mcp. Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content)."
        },
        "on_fail": {
          "type": "string",
          "enum": [
            "retry",
            "continue",
            "stop"
          ],
          "default": "retry",
          "description": "http, openapi, mcp. retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent)."
        }
      },
      "example": {
        "type": "http",
        "connection": "erp",
        "method": "POST",
        "path": "/quotes",
        "query": {},
        "headers": {
          "X-Source": "whatsapp"
        },
        "body": {
          "reference": "{reference}",
          "customer": {
            "name": "{contact.name}",
            "phone": "{contact.phone}"
          },
          "product": "{product}",
          "quantity": "{quantity}",
          "photos": "{files.photos}"
        },
        "save": {
          "erp_id": "$.id",
          "quote_amount": "$.total"
        },
        "on_fail": "retry"
      },
      "description": "One step of an automation: `type` and that type's keys. Every text takes placeholders. `set_status`: Move the submission to a stage. Keys: status = The stage key. note = The note of the change (needed when the stage has require_note). `assign`: Set the assignee. Keys: to = member:<id> = that member. role:<role> = the members with that role in turn (round robin). least_busy:<role> = the member with that role who has the fewest open submissions. none = nobody. `set_field`: Store a value on the submission. Keys: key = An internal field of the form, or any other name that is not one of the form's questions and not a reserved word: it is stored in extra. value = The value, with placeholders. `calculate`: Store the result of a formula. Keys: key = Where the result goes (extra): the same rule as the key of set_field. formula = The formula, up to 500 characters. `tag`: Add or remove tags. Keys: add = Tags to add. remove = Tags to remove. At least one tag in add or remove. `set_priority`: Set the priority. Keys: priority = low, normal, high or urgent. `set_due`: Set the due time. Keys: minutes = Minutes from now, 0 to 525600 (a year). 0 takes the due time off. `reply`: Message the submitter on WhatsApp (by e-mail when they gave only an e-mail address). Outside WhatsApp's reply window the message is held and announced like any reply from the Inbox. Keys: text = The message, up to 4,000 characters. buttons = 0 to 3 buttons: [{id (a-z, 0-9 and _, up to 20 characters, unique in the reply), title (up to 20 characters), set_status}]. Pressing one moves the submission to set_status (when given) and fires the button trigger. file = The key of a photo or document field whose files are sent along, or \"\". link = true: add a button that opens the submitter's status page. `ask_location`: Ask the submitter for their location with WhatsApp's Send location request. The pin is stored on the submission. Keys: text = The message. `send_form`: Send another form as a follow-up. Its submission gets parent = this one, and customer_replied fires here when it arrives. Keys: form = The key of the form to send. text = The message with the form button. prefill = Values for the new form: {\"<field key>\": value}, with placeholders. Up to 30 values. `email`: Send an e-mail. Keys: to = A list of up to 10: owner, assignee, submitter, an address, or a placeholder that holds an address. subject = The subject, up to 200 characters. body = The text, up to 10,000 characters. {answers} gives every answer as Label: value lines. attach_files = true: attach the submission's files (up to 15 MB in all; above that their links are listed). Default false. `notify`: E-mail team members. Keys: to = assignee, role:<role> or all. text = The text, up to 4,000 characters. `http`: Call an outside system with a plain HTTP request. Keys: connection = The key of a connection (kind http or openapi): its base address and sign-in are used. Or \"\" with a full url. method = GET, POST, PUT, PATCH or DELETE. Left out: POST with a body, else GET. path = With a connection: added to its base address, for example /orders/{reference}. Each value a placeholder inserts is percent-encoded. url = Without a connection: the full https address. Placeholders may stand in the path and the query, not in the host name. query = Query parameters: {name: value}, up to 30. headers = Extra headers: {name: value}, up to 10, each value up to 1,000 characters. Sign-in headers come from the connection only. body = Any JSON; sent as application/json. A string that is exactly one placeholder keeps the value's type: \"{quantity}\" sends a number, \"{submission}\" the whole submission object. save = Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content). on_fail = retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent). `openapi`: Call an operation of an imported OpenAPI document. Keys: connection = The key of an openapi connection. operation = A function id of the connection (GET /submit/connections/{key}/functions). params = The operation's parameters by name: {name: value}. Path, query and header parameters go where the document says; body parameters build the JSON body. body = The whole JSON body, instead of body parameters. save = Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content). on_fail = retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent). `mcp`: Call a tool of an MCP server. Keys: connection = The key of an mcp connection. tool = The tool's name (GET /submit/connections/{key}/functions). arguments = The tool's arguments: {name: value}, typed like a JSON body. save = Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content). on_fail = retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent). `wait`: Pause. The rest runs later, and only if the conditions still hold then. Keys: minutes = 1 to 43200 (30 days). `stop`: End the run here."
    },
    "SubmitAutomationInput": {
      "type": "object",
      "required": [
        "name",
        "trigger",
        "actions"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 80,
          "example": "Large quotes go to a manager",
          "description": "What it is called in the list, up to 80 characters. POST /submit/setup replaces an automation with the same name on the same form."
        },
        "form": {
          "type": "string",
          "example": "quote",
          "description": "The key of the form it belongs to, or \"\" for every form."
        },
        "enabled": {
          "type": "boolean",
          "default": true
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Its place in the list, lowest first."
        },
        "trigger": {
          "type": "string",
          "enum": [
            "submitted",
            "status_changed",
            "assigned",
            "updated",
            "note_added",
            "file_added",
            "customer_replied",
            "button",
            "overdue",
            "due",
            "manual"
          ],
          "description": "When it runs. `submitted`: A submission is complete: its files are stored (or 3 minutes passed without them, which is noted on the submission). `status_changed`: The stage changed. Options - to: Stage keys it moved to. [] = any. from: Stage keys it moved from. [] = any. `assigned`: The assignee changed. `updated`: Answers or internal fields were edited. Options - fields: Only when one of these field keys changed. [] = any. `note_added`: A member or the API wrote a note. `file_added`: A file was added after the submission was made. `customer_replied`: The submitter added text or files: after tapping Add more, with a follow-up form, or on their status page. `button`: The submitter pressed a button of a reply. Options - button: The button's id (a-z, 0-9 and _, up to 20 characters). \"\" = any button. `overdue`: The submission is still in the same stage after this long. Fires once per stay in a stage. Options - minutes: Needed: 5 to 43200 (30 days). stages: Only in these stage keys. [] = every open stage. `due`: The due time passed while the submission is open. Fires once per due time. `manual`: A member presses its button on the submission, or POST /submit/submissions/{id}/run names it. Options - label: The button's text, up to 30 characters. Left out: the automation's name."
        },
        "options": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "to": [
              "accepted"
            ],
            "from": []
          },
          "description": "The trigger's options (see trigger). {} when it has none."
        },
        "conditions": {
          "$ref": "#/definitions/SubmitRule",
          "nullable": true,
          "description": "Must hold for the actions to run. In an automation a rule's field may also be status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone. null = always."
        },
        "actions": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "items": {
            "$ref": "#/definitions/SubmitAction"
          },
          "description": "1 to 20 actions, run in order."
        }
      },
      "example": {
        "name": "Price a quote request in the ERP",
        "form": "quote",
        "enabled": true,
        "trigger": "submitted",
        "options": {},
        "conditions": {
          "all": [
            {
              "field": "quantity",
              "gt": 0
            }
          ]
        },
        "actions": [
          {
            "type": "http",
            "connection": "erp",
            "method": "POST",
            "path": "/quotes",
            "query": {},
            "headers": {
              "X-Source": "whatsapp"
            },
            "body": {
              "reference": "{reference}",
              "customer": {
                "name": "{contact.name}",
                "phone": "{contact.phone}"
              },
              "product": "{product}",
              "quantity": "{quantity}",
              "photos": "{files.photos}"
            },
            "save": {
              "erp_id": "$.id",
              "quote_amount": "$.total"
            },
            "on_fail": "retry"
          },
          {
            "type": "set_status",
            "status": "quoted",
            "note": "Priced by the ERP"
          },
          {
            "type": "reply",
            "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
            "buttons": [
              {
                "id": "accept",
                "title": "Accept",
                "set_status": "accepted"
              },
              {
                "id": "decline",
                "title": "Decline",
                "set_status": "declined"
              }
            ],
            "file": "",
            "link": true
          }
        ]
      },
      "description": "An automation: when (`trigger` with its `options`) - if (`conditions`, a rule or null) - do (`actions`, in order). Only the keys listed here are accepted: an unknown key in the document, in `options` or in an action is a problem (`unknown_key`), so a misspelt key is never ignored. Every run is logged step by step, with what was sent and what came back (GET /submit/runs). A change an automation makes can set off other automations, at most 3 levels deep; one submission gets at most 30 runs an hour. Outside calls refuse private and loopback addresses, do not follow redirects, wait at most 15 seconds and read at most 256 KB; a number makes at most 60 a minute and 2,000 a day. Every text of an action, a stage message and the form's reply takes placeholders in curly brackets; a name that is not known stays as typed. {<field key>}: The answer to that field, an internal field, a calculated value or a value an automation saved (any key of answers or extra). {reference}: The submission's reference, for example MR-7Q3M2A. {form}: The form's name. {form_key}: The form's key. {status}: The stage key. {status_name}: The stage's name. {channel}: whatsapp, web, api or staff. {priority}: low, normal, high or urgent. {tags}: The tags, comma separated. {created}: When it was submitted, in the business's local time (yyyy-MM-dd HH:mm). {updated}: When it last changed (local time). {due}: The due time (local time), empty when there is none. {contact.name}: The submitter's name. {contact.phone}: Their number. {contact.email}: Their e-mail address. {assignee.name}: The assigned member's name. {assignee.email}: Their e-mail address. {link}: The submitter's own status page. {desk_link}: The submission in the staff inbox. {answers}: Every answer as Label: value lines. {files}: A link to every file, one per line. Another system can fetch a link for 7 days. {files.<field key>}: The links of that field's files, as one text with a link per line. {note}: The note of the stage change, or the note that set the automation off. {button}: The id of the button the submitter pressed. {business}: The business name. {submission}: In a JSON body or in arguments only: the whole submission object (its times are ISO 8601). {id}, {status_kind}, {verified}, {files_count}, {contact.identity}, {assignee.id}, {prefill.<key>}, {location.address}: More values of the submission that can be read the same way. {= formula }: The result of a formula, for example {= round(quantity * 1.1, 2) }. Formulas (calculated fields, the calculate action, and {= ... } inside any text): numbers, 'texts' in single quotes, field keys, + - * / %, the comparisons == != > >= < <=, and / or / not, brackets, and the functions if(condition, then, else): then when the condition holds, otherwise else (null without an else). min(a, b, ...): The smallest number. max(a, b, ...): The largest number. round(x, decimals): x rounded, half away from zero; decimals 0 to 10, default 0. abs(x): x without its sign. num(x): x as a number, null when it is not one. len(x): The length of a text, or the number of items of a list. coalesce(a, b, ...): The first value that is not empty. lower(x): x in lower case. upper(x): x in upper case. concat(a, b, ...): The values joined as one text. lookup('<list>', id, '<column>'): A column of the item with that id in a list of the number, for example a price. previous('<field>'): The same contact's last value of that field in this form. count_files('<field>'): How many files a photo or document field holds. days_since(date): Whole days from a date (YYYY-MM-DD) to today; negative for a date to come. No loops and no assignment; at most 500 characters; a division by zero or a missing number gives null. Examples: reading - previous('reading'); quantity * lookup('products', product, 'price'); if(usage < 0, 'check', 'ok'); round(amount * 1.2, 2); days_since(purchase_date) > 30 and count_files('receipt') == 0. A rule is {\"field\": \"<key>\", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {\"all\": [rule, ...]} (every one) or {\"any\": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {\"field\": \"deliver\", \"equals\": true}; {\"all\": [{\"field\": \"amount\", \"gt\": 5000}, {\"field\": \"category\", \"in\": [\"plant\", \"vehicle\"]}]}."
    },
    "SubmitAutomationUpdateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 80,
          "example": "Large quotes go to a manager",
          "description": "What it is called in the list, up to 80 characters. POST /submit/setup replaces an automation with the same name on the same form."
        },
        "form": {
          "type": "string",
          "example": "quote",
          "description": "The key of the form it belongs to, or \"\" for every form."
        },
        "enabled": {
          "type": "boolean",
          "default": true
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Its place in the list, lowest first."
        },
        "trigger": {
          "type": "string",
          "enum": [
            "submitted",
            "status_changed",
            "assigned",
            "updated",
            "note_added",
            "file_added",
            "customer_replied",
            "button",
            "overdue",
            "due",
            "manual"
          ],
          "description": "When it runs. `submitted`: A submission is complete: its files are stored (or 3 minutes passed without them, which is noted on the submission). `status_changed`: The stage changed. Options - to: Stage keys it moved to. [] = any. from: Stage keys it moved from. [] = any. `assigned`: The assignee changed. `updated`: Answers or internal fields were edited. Options - fields: Only when one of these field keys changed. [] = any. `note_added`: A member or the API wrote a note. `file_added`: A file was added after the submission was made. `customer_replied`: The submitter added text or files: after tapping Add more, with a follow-up form, or on their status page. `button`: The submitter pressed a button of a reply. Options - button: The button's id (a-z, 0-9 and _, up to 20 characters). \"\" = any button. `overdue`: The submission is still in the same stage after this long. Fires once per stay in a stage. Options - minutes: Needed: 5 to 43200 (30 days). stages: Only in these stage keys. [] = every open stage. `due`: The due time passed while the submission is open. Fires once per due time. `manual`: A member presses its button on the submission, or POST /submit/submissions/{id}/run names it. Options - label: The button's text, up to 30 characters. Left out: the automation's name."
        },
        "options": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "to": [
              "accepted"
            ],
            "from": []
          },
          "description": "The trigger's options (see trigger). {} when it has none."
        },
        "conditions": {
          "$ref": "#/definitions/SubmitRule",
          "nullable": true,
          "description": "Must hold for the actions to run. In an automation a rule's field may also be status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone. null = always."
        },
        "actions": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "items": {
            "$ref": "#/definitions/SubmitAction"
          },
          "description": "1 to 20 actions, run in order."
        }
      },
      "description": "Either the whole automation (with trigger and actions): it replaces what is stored. Or a part: a body with neither trigger nor actions changes only the keys it has (name, form, enabled, options, conditions, position). Either way the result is checked as a whole."
    },
    "SubmitAutomation": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 80,
          "example": "Large quotes go to a manager",
          "description": "What it is called in the list, up to 80 characters. POST /submit/setup replaces an automation with the same name on the same form."
        },
        "form": {
          "type": "string",
          "example": "quote",
          "description": "The key of the form it belongs to, or \"\" for every form."
        },
        "enabled": {
          "type": "boolean",
          "default": true
        },
        "position": {
          "type": "integer"
        },
        "trigger": {
          "type": "string",
          "enum": [
            "submitted",
            "status_changed",
            "assigned",
            "updated",
            "note_added",
            "file_added",
            "customer_replied",
            "button",
            "overdue",
            "due",
            "manual"
          ],
          "description": "When it runs. `submitted`: A submission is complete: its files are stored (or 3 minutes passed without them, which is noted on the submission). `status_changed`: The stage changed. Options - to: Stage keys it moved to. [] = any. from: Stage keys it moved from. [] = any. `assigned`: The assignee changed. `updated`: Answers or internal fields were edited. Options - fields: Only when one of these field keys changed. [] = any. `note_added`: A member or the API wrote a note. `file_added`: A file was added after the submission was made. `customer_replied`: The submitter added text or files: after tapping Add more, with a follow-up form, or on their status page. `button`: The submitter pressed a button of a reply. Options - button: The button's id (a-z, 0-9 and _, up to 20 characters). \"\" = any button. `overdue`: The submission is still in the same stage after this long. Fires once per stay in a stage. Options - minutes: Needed: 5 to 43200 (30 days). stages: Only in these stage keys. [] = every open stage. `due`: The due time passed while the submission is open. Fires once per due time. `manual`: A member presses its button on the submission, or POST /submit/submissions/{id}/run names it. Options - label: The button's text, up to 30 characters. Left out: the automation's name."
        },
        "options": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "to": [
              "accepted"
            ],
            "from": []
          },
          "description": "The trigger's options (see trigger). {} when it has none."
        },
        "conditions": {
          "$ref": "#/definitions/SubmitRule",
          "nullable": true,
          "description": "Must hold for the actions to run. In an automation a rule's field may also be status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone. null = always."
        },
        "actions": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "items": {
            "$ref": "#/definitions/SubmitAction"
          },
          "description": "1 to 20 actions, run in order."
        },
        "id": {
          "type": "integer",
          "example": 31
        },
        "sentence": {
          "type": "string",
          "description": "The automation in one sentence, as the dashboard lists it."
        },
        "runs": {
          "type": "integer",
          "description": "How often it ran."
        },
        "failures": {
          "type": "integer"
        },
        "last_run": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_error": {
          "type": "string"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "A saved automation: the document that was sent (SubmitAutomationInput explains every trigger, action, placeholder and formula function) plus its id and counters."
    },
    "SubmitRunStep": {
      "type": "object",
      "properties": {
        "n": {
          "type": "integer",
          "description": "The action's number in the automation, counted from 1."
        },
        "type": {
          "type": "string",
          "description": "The action type."
        },
        "ok": {
          "type": "boolean"
        },
        "ms": {
          "type": "integer"
        },
        "summary": {
          "type": "string",
          "description": "What happened, in words."
        },
        "error": {
          "type": "string"
        },
        "request": {
          "type": "object",
          "additionalProperties": true,
          "description": "Outside calls only: method, address and what was sent. Never a secret or a sign-in header."
        },
        "response": {
          "type": "object",
          "additionalProperties": true,
          "description": "Outside calls only: status and the first 2,000 characters of the answer."
        },
        "try": {
          "type": "integer",
          "description": "Only on a retry of an outside call: 2, 3 or 4."
        }
      }
    },
    "SubmitRun": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "0 for a try: it is not stored."
        },
        "automation_id": {
          "type": "integer"
        },
        "automation": {
          "type": "string",
          "description": "Its name."
        },
        "submission": {
          "type": "string",
          "description": "The submission's reference."
        },
        "trigger": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "ok",
            "failed",
            "waiting",
            "skipped"
          ],
          "description": "ok: it ran to the end; an action that did not work without stopping the run (a refused stage, a reply that could not be sent) has ok false in its step and its message in error. failed: an outside call ran out of retries, or failed with on_fail stop. waiting: paused by a wait action, between retries, or queued (due says when it continues). skipped: the conditions did not hold, or the automation or the submission was gone."
        },
        "attempt": {
          "type": "integer"
        },
        "steps": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitRunStep"
          }
        },
        "error": {
          "type": "string"
        },
        "test": {
          "type": "boolean",
          "description": "true: a try, nothing was changed or sent."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "finished": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "due": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      },
      "description": "One run of an automation on one submission, with every step."
    },
    "SubmitConnectionInput": {
      "type": "object",
      "example": {
        "name": "ERP",
        "kind": "http",
        "base_url": "https://erp.example.com/api",
        "auth": {
          "type": "bearer",
          "secret": "YOUR_ERP_TOKEN"
        },
        "headers": {
          "X-Tenant": "acme"
        },
        "enabled": true
      },
      "description": "An outside system automations can call. A new connection needs name and kind; a later PUT without kind changes only the keys it names. `http`: A base address and a sign-in. An http action names the method, path, query, headers and JSON body. `openapi`: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters. `mcp`: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments. Sign-in (auth.type): `none`: No sign-in. `bearer`: Authorization: Bearer <secret>. `header`: The header called name carries the secret. `basic`: Basic sign-in with username and the secret as the password. `query`: The query parameter called name carries the secret. The secret is stored encrypted and never returned: leave auth.secret out of a later PUT to keep it; when the address changes (scheme, host or port) the secret must be sent again. Every address must be https and public: private, loopback, link-local and cloud metadata addresses are refused (checked after the name is looked up), redirects are not followed, a call waits at most 15 seconds and reads at most 256 KB. A connection keeps at most 300 functions with 40 parameters each.",
      "properties": {
        "name": {
          "type": "string",
          "example": "ERP"
        },
        "kind": {
          "type": "string",
          "enum": [
            "http",
            "openapi",
            "mcp"
          ],
          "description": "`http`: A base address and a sign-in. An http action names the method, path, query, headers and JSON body. `openapi`: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters. `mcp`: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments."
        },
        "base_url": {
          "type": "string",
          "example": "https://erp.example.com/api",
          "description": "https only. http: the base every path is added to. openapi: the API's base; left empty, the document's first server is used. mcp: the server's address."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "example": {
            "X-Tenant": "acme"
          },
          "description": "Up to 5 fixed headers sent with every call. Not secret: they are shown again."
        },
        "spec_url": {
          "type": "string",
          "example": "https://erp.example.com/openapi.json",
          "description": "openapi only: where the OpenAPI document (JSON) is read from."
        },
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "false: actions that use it fail without calling out."
        },
        "auth": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "none",
                "bearer",
                "header",
                "basic",
                "query"
              ],
              "description": "`none`: No sign-in. `bearer`: Authorization: Bearer <secret>. `header`: The header called name carries the secret. `basic`: Basic sign-in with username and the secret as the password. `query`: The query parameter called name carries the secret."
            },
            "name": {
              "type": "string",
              "description": "header: the header's name. query: the parameter's name."
            },
            "username": {
              "type": "string",
              "description": "basic only."
            },
            "secret": {
              "type": "string",
              "description": "The token, key or password. Write-only: never shown again. Left out: the stored one is kept."
            }
          },
          "required": [
            "type"
          ]
        },
        "spec": {
          "type": "object",
          "additionalProperties": true,
          "description": "openapi only: the OpenAPI document itself, posted once instead of spec_url."
        }
      }
    },
    "SubmitConnection": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "ERP"
        },
        "kind": {
          "type": "string",
          "enum": [
            "http",
            "openapi",
            "mcp"
          ],
          "description": "`http`: A base address and a sign-in. An http action names the method, path, query, headers and JSON body. `openapi`: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters. `mcp`: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments."
        },
        "base_url": {
          "type": "string",
          "example": "https://erp.example.com/api",
          "description": "https only. http: the base every path is added to. openapi: the API's base; left empty, the document's first server is used. mcp: the server's address."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "example": {
            "X-Tenant": "acme"
          },
          "description": "Up to 5 fixed headers sent with every call. Not secret: they are shown again."
        },
        "spec_url": {
          "type": "string",
          "example": "https://erp.example.com/openapi.json",
          "description": "openapi only: where the OpenAPI document (JSON) is read from."
        },
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "false: actions that use it fail without calling out."
        },
        "key": {
          "type": "string",
          "example": "erp"
        },
        "auth": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "none",
                "bearer",
                "header",
                "basic",
                "query"
              ]
            },
            "name": {
              "type": "string"
            },
            "username": {
              "type": "string"
            },
            "has_secret": {
              "type": "boolean",
              "description": "A secret is stored. It is never returned."
            }
          }
        },
        "functions_count": {
          "type": "integer",
          "description": "openapi, mcp: how many operations or tools are known."
        },
        "functions_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When they were last read."
        },
        "last_ok": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "The last call or test that worked."
        },
        "last_error": {
          "type": "string"
        },
        "used_by": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The names of the automations that use it."
        }
      },
      "description": "A saved connection. The secret is never in an answer."
    },
    "SubmitConnectionFunction": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "createTicket",
          "description": "openapi: the operationId (or method and path made into a name). mcp: the tool's name. What an action's operation or tool takes."
        },
        "title": {
          "type": "string"
        },
        "method": {
          "type": "string",
          "description": "openapi only."
        },
        "path": {
          "type": "string",
          "description": "openapi only."
        },
        "params": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "in": {
                "type": "string",
                "enum": [
                  "path",
                  "query",
                  "header",
                  "body"
                ],
                "description": "Where it goes. mcp arguments are all body."
              },
              "type": {
                "type": "string"
              },
              "required": {
                "type": "boolean"
              },
              "description": {
                "type": "string"
              }
            }
          }
        },
        "has_body": {
          "type": "boolean",
          "description": "The operation takes a JSON body."
        }
      },
      "description": "One thing an action can call on a connection: an operation of the OpenAPI document or a tool of the MCP server, with its parameters."
    },
    "SubmitMember": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Sam"
        },
        "role": {
          "type": "string",
          "enum": [
            "owner",
            "admin",
            "manager",
            "agent",
            "viewer"
          ],
          "description": "`owner`: The account owner. Every ability. Cannot be changed or removed. `admin`: Every ability. `manager`: note, reply, edit, stage, assign, files, export, delete, run. `agent`: note, reply, edit, stage, files, run. `viewer`: Sees submissions, changes nothing."
        },
        "abilities": {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          },
          "description": "What the member may do now: the role's set with their own changes. `note`: Write internal notes. `reply`: Reply to the submitter. `edit`: Edit answers and internal fields. `stage`: Change the stage. `assign`: Assign to anyone (an agent may always take a submission themselves). `files`: Add and remove files. `export`: Export. `delete`: Delete and restore. `run`: Run manual automations. `forms`: Manage forms and lists. `automations`: Manage automations and connections. `team`: Manage the team."
        },
        "forms": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Only these forms (keys). [] = every form."
        },
        "own_only": {
          "type": "boolean",
          "default": false,
          "description": "Sees only what is assigned to them."
        },
        "see_unassigned": {
          "type": "boolean",
          "default": true,
          "description": "With own_only: also sees unassigned submissions, to pick them up."
        },
        "hide_contacts": {
          "type": "boolean",
          "default": false,
          "description": "Numbers, e-mail addresses and answers of type phone or email are masked for this member."
        },
        "notify": {
          "type": "object",
          "properties": {
            "assigned": {
              "type": "boolean",
              "description": "E-mail them when a submission is assigned to them."
            },
            "created": {
              "type": "boolean",
              "description": "E-mail them for every new submission they may see."
            }
          }
        },
        "id": {
          "type": "integer",
          "example": 12
        },
        "email": {
          "type": "string",
          "example": "sam@example.com"
        },
        "overrides": {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          },
          "description": "Only the member's own changes to the role's set."
        },
        "status": {
          "type": "string",
          "enum": [
            "invited",
            "active",
            "removed"
          ]
        },
        "invite_expired": {
          "type": "boolean",
          "description": "true: the invitation was not accepted in time; invite the address again."
        },
        "invited": {
          "type": "string",
          "format": "date-time"
        },
        "accepted": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_seen": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "open_count": {
          "type": "integer",
          "description": "Open submissions assigned to them."
        }
      },
      "description": "A person who works in the shared inbox. The assignee of a submission is a member id."
    },
    "SubmitSettings": {
      "type": "object",
      "additionalProperties": true,
      "example": {
        "business_name": "",
        "default_prefix": "SI",
        "menu_words": [
          "form",
          "forms",
          "report",
          "submit"
        ],
        "menu_text": "What would you like to send us?",
        "status_words": [
          "status"
        ],
        "other_words_limit": 10,
        "notify_email": "",
        "timezone": "",
        "brand": {
          "color": "#2DAE5C",
          "background": "#FFFFFF",
          "hide_branding": false
        },
        "views": [
          {
            "key": "urgent",
            "name": "Urgent",
            "filter": {
              "priority": [
                "urgent"
              ],
              "status_kind": [
                "open"
              ]
            }
          }
        ],
        "retention_days": 0
      },
      "description": "The number's Submit-Info settings.",
      "properties": {
        "business_name": {
          "type": "string",
          "description": "The {business} placeholder and the name on the web pages. \"\" = the number's verified name."
        },
        "default_prefix": {
          "type": "string",
          "example": "SI",
          "description": "2 to 4 letters A-Z: the reference prefix of forms that have none."
        },
        "menu_words": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "description": "A contact who sends one of these gets the form (one form) or a menu of the forms (several). [] = no menu."
        },
        "menu_text": {
          "type": "string",
          "description": "The text above the menu."
        },
        "status_words": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 5,
          "description": "A contact with a submission of the last 90 days who sends one of these gets its stage."
        },
        "other_words_limit": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "default": 10,
          "description": "A form's word starts the form only when the message has fewer than this many other words, so a long message never starts a form. 0 = a message of any length. Menu and status words also need a message of at most 5 words."
        },
        "notify_email": {
          "type": "string",
          "description": "Where the business's e-mails go. \"\" = the number's Default To address. \"off\" = none."
        },
        "timezone": {
          "type": "string",
          "example": "Australia/Sydney",
          "description": "\"\" = the number's time zone."
        },
        "brand": {
          "type": "object",
          "properties": {
            "color": {
              "type": "string",
              "example": "#2DAE5C"
            },
            "background": {
              "type": "string",
              "example": "#FFFFFF"
            },
            "hide_branding": {
              "type": "boolean"
            }
          },
          "description": "The look of the web form and the status page."
        },
        "views": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "filter": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "description": "Saved inbox views the whole team shares."
        },
        "retention_days": {
          "type": "integer",
          "default": 0,
          "description": "For forms that set none: 0 = keep, else closed submissions are erased after this many days (30 to 3650)."
        }
      }
    },
    "SubmitSetup": {
      "type": "object",
      "example": {
        "dry_run": true,
        "settings": {
          "enabled": true
        },
        "lists": [
          {
            "key": "products",
            "name": "Products",
            "items": [
              {
                "id": "pump-s",
                "title": "Pump, small",
                "description": "Up to 40 l/min",
                "price": 240
              },
              {
                "id": "pump-l",
                "title": "Pump, large",
                "description": "Up to 120 l/min",
                "price": 610
              }
            ]
          }
        ],
        "connections": [
          {
            "name": "ERP",
            "kind": "http",
            "base_url": "https://erp.example.com/api",
            "auth": {
              "type": "bearer",
              "secret": "YOUR_ERP_TOKEN"
            },
            "headers": {
              "X-Tenant": "acme"
            },
            "enabled": true,
            "key": "erp"
          }
        ],
        "forms": [
          {
            "key": "quote",
            "name": "Quote request",
            "definition": {
              "title": "Quote request",
              "description": "Tell us what you need and we will send a price.",
              "prefix": "QR",
              "steps": [
                {
                  "key": "need",
                  "title": "What you need",
                  "text": "",
                  "show_if": null,
                  "fields": [
                    {
                      "key": "product",
                      "type": "select",
                      "label": "Product",
                      "required": true,
                      "list": "products"
                    },
                    {
                      "key": "quantity",
                      "type": "number",
                      "label": "How many?",
                      "required": true,
                      "min": 1,
                      "max": 10000,
                      "decimals": 0
                    },
                    {
                      "key": "notes",
                      "type": "textarea",
                      "label": "Anything we should know?",
                      "required": false,
                      "max_length": 1000
                    },
                    {
                      "key": "photos",
                      "type": "photo",
                      "label": "Photos of the site (optional)",
                      "required": false,
                      "max_files": 3,
                      "source": "any"
                    },
                    {
                      "key": "quote_amount",
                      "type": "number",
                      "label": "Quote amount",
                      "internal": true,
                      "decimals": 2,
                      "unit": "USD"
                    }
                  ]
                },
                {
                  "key": "delivery",
                  "title": "Delivery",
                  "text": "",
                  "show_if": null,
                  "fields": [
                    {
                      "key": "deliver",
                      "type": "yesno",
                      "label": "Do you need delivery?",
                      "required": true
                    }
                  ]
                },
                {
                  "key": "delivery_address",
                  "title": "Delivery address",
                  "text": "",
                  "show_if": {
                    "field": "deliver",
                    "equals": true
                  },
                  "fields": [
                    {
                      "key": "address",
                      "type": "textarea",
                      "label": "Where should we deliver?",
                      "required": true,
                      "max_length": 300
                    }
                  ]
                }
              ],
              "stages": [
                {
                  "key": "new",
                  "name": "New",
                  "kind": "open",
                  "color": "blue",
                  "set_by": [],
                  "require_note": false,
                  "message": ""
                },
                {
                  "key": "quoted",
                  "name": "Quoted",
                  "kind": "open",
                  "color": "amber",
                  "set_by": [],
                  "require_note": false,
                  "message": ""
                },
                {
                  "key": "accepted",
                  "name": "Accepted",
                  "kind": "done",
                  "color": "green",
                  "set_by": [],
                  "require_note": false,
                  "message": "Thank you. We will be in touch about {reference} shortly."
                },
                {
                  "key": "declined",
                  "name": "Declined",
                  "kind": "cancelled",
                  "color": "grey",
                  "set_by": [],
                  "require_note": false,
                  "message": ""
                }
              ],
              "trigger": {
                "words": [
                  "quote"
                ],
                "header": "",
                "body": "Tap the button to ask for a quote.",
                "button": "Get a quote",
                "footer": ""
              },
              "after": {
                "review_step": true,
                "reply": "Thanks {contact.name}. Your request {reference} is with us; the price follows shortly.",
                "allow_additions": true,
                "status_page": true
              },
              "calculated": [
                {
                  "key": "estimate",
                  "label": "Estimate",
                  "formula": "quantity * lookup('products', product, 'price')",
                  "unit": "USD",
                  "decimals": 2
                }
              ]
            }
          }
        ],
        "automations": [
          {
            "name": "Price a quote request in the ERP",
            "form": "quote",
            "enabled": true,
            "trigger": "submitted",
            "options": {},
            "conditions": {
              "all": [
                {
                  "field": "quantity",
                  "gt": 0
                }
              ]
            },
            "actions": [
              {
                "type": "http",
                "connection": "erp",
                "method": "POST",
                "path": "/quotes",
                "query": {},
                "headers": {
                  "X-Source": "whatsapp"
                },
                "body": {
                  "reference": "{reference}",
                  "customer": {
                    "name": "{contact.name}",
                    "phone": "{contact.phone}"
                  },
                  "product": "{product}",
                  "quantity": "{quantity}",
                  "photos": "{files.photos}"
                },
                "save": {
                  "erp_id": "$.id",
                  "quote_amount": "$.total"
                },
                "on_fail": "retry"
              },
              {
                "type": "set_status",
                "status": "quoted",
                "note": "Priced by the ERP"
              },
              {
                "type": "reply",
                "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                "buttons": [
                  {
                    "id": "accept",
                    "title": "Accept",
                    "set_status": "accepted"
                  },
                  {
                    "id": "decline",
                    "title": "Decline",
                    "set_status": "declined"
                  }
                ],
                "file": "",
                "link": true
              }
            ]
          },
          {
            "name": "Tell the owner when a quote is accepted",
            "form": "quote",
            "enabled": true,
            "trigger": "status_changed",
            "options": {
              "to": [
                "accepted"
              ],
              "from": []
            },
            "conditions": null,
            "actions": [
              {
                "type": "email",
                "to": [
                  "owner"
                ],
                "subject": "Quote {reference} accepted: {quote_amount} USD",
                "body": "{contact.name} ({contact.phone}) accepted.\n\n{answers}\n\n{desk_link}",
                "attach_files": false
              }
            ]
          }
        ],
        "publish": [
          "quote"
        ]
      },
      "description": "A whole solution in one document: settings, lists, connections, forms and automations, applied in that order. Every part is optional. What already exists under the same key is REPLACED: lists, connections and forms by `key`, automations by `name` within the same form. Parts and keys the document does not name are left alone. The document is checked as a whole (each form, each automation, and the links between them: a select's list, an action's connection, form, stage and field keys). With any problem nothing is written. `preset` in place of the parts installs a ready-made solution (GET /submit/presets).",
      "properties": {
        "dry_run": {
          "type": "boolean",
          "default": false,
          "description": "true: check only. The answer lists every problem and what would be written; nothing is changed."
        },
        "replace": {
          "type": "boolean",
          "default": true,
          "description": "Left out or true: a form whose key already exists is replaced by the one in the document. false: such a form is not overwritten - the answer is 409 `form_exists` and nothing is written. Lists, connections and automations of the same key / name are always replaced."
        },
        "preset": {
          "type": "string",
          "example": "quote",
          "description": "A preset's key, instead of lists, connections, forms and automations."
        },
        "settings": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "true switches Submit-Info on for the number."
            },
            "config": {
              "$ref": "#/definitions/SubmitSettings"
            }
          },
          "description": "As PUT /submit/settings."
        },
        "lists": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "example": "products"
              },
              "name": {
                "type": "string"
              },
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/SubmitListItem"
                }
              }
            },
            "required": [
              "key",
              "name",
              "items"
            ]
          },
          "description": "As PUT /submit/lists/{key}, with the key inside."
        },
        "connections": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitConnectionInput"
          },
          "description": "As PUT /submit/connections/{key}, with `key` inside each one."
        },
        "forms": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "example": "quote"
              },
              "name": {
                "type": "string",
                "example": "Quote request"
              },
              "definition": {
                "$ref": "#/definitions/SubmitFormDefinition"
              }
            },
            "required": [
              "key",
              "name",
              "definition"
            ]
          },
          "description": "As POST /submit/forms."
        },
        "automations": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitAutomationInput"
          },
          "description": "As POST /submit/automations."
        },
        "publish": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "quote"
          ],
          "description": "Form keys to publish to WhatsApp after everything was written without a problem. Ignored by a dry run."
        }
      }
    },
    "SubmitGuide": {
      "type": "object",
      "additionalProperties": true,
      "description": "Everything an agent needs to configure Submit-Info, as one JSON document. product, summary; how_to (the five steps in order); form {keys (every key of the definition), key_rule, field_keys (the keys every field takes), field_types [{type, value, keys, whatsapp, notes}], internal_types, reserved_keys, whatsapp, stage {keys, example}, rule {shape, operators, groups, comparing, in_show_if, in_automations, example}}; automation {keys, triggers [{trigger, when, options}], trigger_options, actions [{type, does, keys, example}], placeholders [{name, is}], placeholder_notes, formula {language, functions [{name, usage, does}], examples}, json_path, limits}; connection {keys, kinds [{kind, use}], auth_types [{type, use}], limits, example}; member {keys, roles {role: [abilities]}, abilities, notes}; settings {enabled, config}; limits; setup {shape, order, replaces}; presets [{key, name, description, category}]; examples (three complete setup documents: a meter reading form that posts to a billing API, a quote request, a field job report that calls an MCP tool); this_number (what the number already has). Keys may be added over time.",
      "properties": {
        "product": {
          "type": "string"
        },
        "summary": {
          "type": "string"
        },
        "how_to": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "form": {
          "type": "object",
          "additionalProperties": true
        },
        "automation": {
          "type": "object",
          "additionalProperties": true
        },
        "connection": {
          "type": "object",
          "additionalProperties": true
        },
        "member": {
          "type": "object",
          "additionalProperties": true
        },
        "settings": {
          "type": "object",
          "additionalProperties": true
        },
        "limits": {
          "type": "object",
          "additionalProperties": true
        },
        "setup": {
          "type": "object",
          "additionalProperties": true
        },
        "presets": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitPreset"
          }
        },
        "examples": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "setup": {
                "$ref": "#/definitions/SubmitSetup"
              }
            }
          }
        },
        "this_number": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "lists": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "connections": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "description": "The keys already in use on this number."
        }
      }
    },
    "SubmitPreset": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "example": "quote"
        },
        "name": {
          "type": "string",
          "example": "Quote request"
        },
        "description": {
          "type": "string"
        },
        "category": {
          "type": "string"
        }
      },
      "description": "A ready-made solution: forms, stages and automations for one kind of work."
    },
    "SubmitSettingsUpdateRequest": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Switches Submit-Info on or off for the number: words, links and automations."
        },
        "config": {
          "$ref": "#/definitions/SubmitSettings"
        }
      },
      "description": "enabled, config, or both."
    },
    "SubmitFormCreateRequest": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "example": "meter_reading",
          "description": "The form's key: lower case letters, digits and _, starting with a letter, at most 40 characters (check is reserved). Left out: made from the name. It is part of the web address and cannot be changed later."
        },
        "name": {
          "type": "string",
          "example": "Meter reading",
          "description": "The name in the dashboard and the inbox. Needed with definition."
        },
        "definition": {
          "$ref": "#/definitions/SubmitFormDefinition"
        },
        "preset": {
          "type": "string",
          "example": "quote",
          "description": "Instead of a definition: install this preset (GET /submit/presets): its form together with the lists and automations that belong to it. key and name, when given, rename its form."
        }
      },
      "description": "name and definition, or preset."
    },
    "SubmitFormUpdateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean",
          "description": "false: the form stops answering its words and links."
        },
        "archived": {
          "type": "boolean",
          "description": "true: hide the form and stop taking submissions. Its submissions stay."
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Its place in the lists and in the forms menu, lowest first."
        },
        "definition": {
          "$ref": "#/definitions/SubmitFormDefinition",
          "description": "The WHOLE new definition: it replaces the working copy."
        }
      },
      "description": "Any of these; what is left out stays."
    },
    "SubmitFormSendRequest": {
      "type": "object",
      "properties": {
        "to": {
          "type": "string",
          "example": "61412345678",
          "description": "The contact's WhatsApp number with country code, digits only, or their business-scoped user id."
        },
        "name": {
          "type": "string",
          "example": "John Smith",
          "description": "Their name, when you know it."
        },
        "prefill": {
          "type": "object",
          "additionalProperties": true,
          "example": {
            "job_no": "J-20931"
          },
          "description": "Values the form starts with: {key: value}. A field reads one with default {prefill.<key>}; a hidden field carries it into the submission unseen."
        },
        "parent": {
          "type": "string",
          "example": "QR-4HT9XC",
          "description": "A submission (id or reference) the new one adds to: a follow-up."
        },
        "text": {
          "type": "string",
          "description": "The message with the form button. Left out: the form's own trigger body."
        },
        "link_only": {
          "type": "boolean",
          "default": false,
          "description": "true: send nothing, only make the personal link and return it."
        }
      },
      "required": [
        "to"
      ]
    },
    "SubmitListSetRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 60,
          "example": "Products",
          "description": "Left out: the key."
        },
        "items": {
          "type": "array",
          "maxItems": 1000,
          "items": {
            "$ref": "#/definitions/SubmitListItem"
          },
          "description": "ALL the items: they replace what is stored. Up to 1,000 items and 200 KB."
        }
      },
      "required": [
        "items"
      ]
    },
    "SubmissionCreateRequest": {
      "type": "object",
      "properties": {
        "form": {
          "type": "string",
          "example": "meter_reading",
          "description": "The form's key. An archived form takes no submissions."
        },
        "contact": {
          "type": "string",
          "example": "61412345678",
          "description": "The person's WhatsApp number with country code, digits only, or their business-scoped user id. Left out: a submission without a WhatsApp contact."
        },
        "contact_name": {
          "type": "string"
        },
        "contact_email": {
          "type": "string",
          "format": "email"
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "Field key -> value, typed as the field types say. Checked like a customer's answers: required fields, ranges, choice ids."
        },
        "extra": {
          "type": "object",
          "additionalProperties": true,
          "description": "Values for internal fields, and anything else to keep with it."
        },
        "status": {
          "type": "string",
          "description": "A stage key to start in. Left out: the form's first stage."
        },
        "assignee": {
          "type": "integer",
          "example": 12,
          "description": "A member's id (GET /submit/members) to assign it to at once."
        },
        "location": {
          "type": "object",
          "description": "Where it is: a pin and / or an address. lat and lng come together.",
          "example": {
            "lat": -33.86,
            "lng": 151.21,
            "address": "12 Example St, Sydney"
          },
          "properties": {
            "lat": {
              "type": "number"
            },
            "lng": {
              "type": "number"
            },
            "name": {
              "type": "string"
            },
            "address": {
              "type": "string"
            }
          }
        },
        "files": {
          "type": "array",
          "maxItems": 20,
          "description": "Files for photo and document fields: up to 20 in one request, 10 MB each. Add more with POST /submit/submissions/{id}/files.",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string",
                "description": "The field's key."
              },
              "name": {
                "type": "string",
                "example": "meter.jpg"
              },
              "mime": {
                "type": "string",
                "example": "image/jpeg"
              },
              "data": {
                "type": "string",
                "description": "The bytes, base64."
              }
            },
            "required": [
              "name",
              "data"
            ]
          }
        }
      },
      "required": [
        "form",
        "answers"
      ]
    },
    "SubmissionUpdateRequest": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "example": "checked",
          "description": "A stage key of the submission's form."
        },
        "note": {
          "type": "string",
          "maxLength": 4000,
          "description": "With status: the note of the change (needed when the stage has require_note; a stage's message can show it to the submitter as {note}). Alone: written as an internal note."
        },
        "priority": {
          "type": "string",
          "enum": [
            "low",
            "normal",
            "high",
            "urgent"
          ]
        },
        "assignee": {
          "type": "integer",
          "nullable": true,
          "example": 12,
          "description": "A member's id (GET /submit/members). 0 or null = nobody."
        },
        "due": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "ISO 8601. null or an empty text takes the due time off."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "ALL the tags: they replace what is there. Up to 20, 40 characters each."
        },
        "tags_add": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags to add."
        },
        "tags_remove": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags to remove."
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "Answers to change: only the keys given are changed; null removes a value. Checked like a customer's answers."
        },
        "extra": {
          "type": "object",
          "additionalProperties": true,
          "description": "Internal fields and other values to change: only the keys given are changed; null removes a value."
        },
        "location": {
          "type": "object",
          "description": "Where it is: a pin and / or an address. lat and lng come together.",
          "example": {
            "lat": -33.86,
            "lng": 151.21,
            "address": "12 Example St, Sydney"
          },
          "properties": {
            "lat": {
              "type": "number"
            },
            "lng": {
              "type": "number"
            },
            "name": {
              "type": "string"
            },
            "address": {
              "type": "string"
            }
          }
        }
      },
      "description": "Any of these; what is left out stays. 400 nothing_to_change when the body names none of them."
    },
    "SubmissionNoteRequest": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 4000,
          "example": "The customer called: the meter was replaced in October."
        }
      },
      "required": [
        "text"
      ]
    },
    "SubmissionReplyRequest": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 4000,
          "description": "The message. Needed unless a file is sent."
        },
        "buttons": {
          "type": "array",
          "maxItems": 3,
          "description": "Up to 3 buttons. Pressing one moves the submission to set_status (when given), sends submission.customer_replied and fires automations with the button trigger.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "example": "fixed",
                "description": "Your name for the button: it comes back in reply.button. Left out: one is made."
              },
              "title": {
                "type": "string",
                "maxLength": 20,
                "example": "Yes, fixed"
              },
              "set_status": {
                "type": "string",
                "example": "resolved",
                "description": "A stage key of the form."
              }
            },
            "required": [
              "title"
            ]
          }
        },
        "file": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "example": "quote.pdf"
            },
            "mime": {
              "type": "string",
              "example": "application/pdf"
            },
            "data": {
              "type": "string",
              "description": "The bytes, base64. 10 MB at most."
            }
          },
          "required": [
            "name",
            "data"
          ],
          "description": "A file sent with the reply. It is stored with the submission too."
        },
        "link": {
          "type": "boolean",
          "default": false,
          "description": "true: add a button that opens the submitter's own page with the status and the history."
        }
      }
    },
    "SubmissionFileRequest": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string",
          "description": "A photo or document field's key. Left out: a loose file of the submission."
        },
        "name": {
          "type": "string",
          "example": "report.pdf"
        },
        "mime": {
          "type": "string",
          "example": "application/pdf"
        },
        "data": {
          "type": "string",
          "description": "The bytes, base64. 10 MB at most."
        }
      },
      "required": [
        "name",
        "data"
      ]
    },
    "SubmissionRunRequest": {
      "type": "object",
      "properties": {
        "automation_id": {
          "type": "integer",
          "example": 31,
          "description": "A manual automation of the submission's form: one of the submission's actions[].id."
        }
      },
      "required": [
        "automation_id"
      ]
    },
    "SubmitMemberInviteRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Sam"
        },
        "role": {
          "type": "string",
          "enum": [
            "admin",
            "manager",
            "agent",
            "viewer"
          ],
          "description": "A named starting set of abilities. `admin`: Every ability. `manager`: note, reply, edit, stage, assign, files, export, delete, run. `agent`: note, reply, edit, stage, files, run. `viewer`: Sees submissions, changes nothing."
        },
        "abilities": {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          },
          "example": {
            "export": true
          },
          "description": "Changes to the role's set: {ability: true or false}. In an update it replaces the member's earlier changes. `note`: Write internal notes. `reply`: Reply to the submitter. `edit`: Edit answers and internal fields. `stage`: Change the stage. `assign`: Assign to anyone (an agent may always take a submission themselves). `files`: Add and remove files. `export`: Export. `delete`: Delete and restore. `run`: Run manual automations. `forms`: Manage forms and lists. `automations`: Manage automations and connections. `team`: Manage the team."
        },
        "forms": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Only these forms (keys). [] = every form."
        },
        "own_only": {
          "type": "boolean",
          "default": false,
          "description": "Sees only what is assigned to them."
        },
        "see_unassigned": {
          "type": "boolean",
          "default": true,
          "description": "With own_only: also sees unassigned submissions, to pick them up."
        },
        "hide_contacts": {
          "type": "boolean",
          "default": false,
          "description": "Numbers, e-mail addresses and answers of type phone or email are masked for this member."
        },
        "notify": {
          "type": "object",
          "properties": {
            "assigned": {
              "type": "boolean",
              "description": "E-mail them when a submission is assigned to them."
            },
            "created": {
              "type": "boolean",
              "description": "E-mail them for every new submission they may see."
            }
          }
        },
        "email": {
          "type": "string",
          "format": "email",
          "example": "sam@example.com",
          "description": "They sign in with this address. It cannot be changed later: remove the member and invite the new address."
        }
      },
      "required": [
        "email",
        "role"
      ]
    },
    "SubmitMemberUpdateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Sam"
        },
        "role": {
          "type": "string",
          "enum": [
            "admin",
            "manager",
            "agent",
            "viewer"
          ],
          "description": "A named starting set of abilities. `admin`: Every ability. `manager`: note, reply, edit, stage, assign, files, export, delete, run. `agent`: note, reply, edit, stage, files, run. `viewer`: Sees submissions, changes nothing."
        },
        "abilities": {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          },
          "example": {
            "export": true
          },
          "description": "Changes to the role's set: {ability: true or false}. In an update it replaces the member's earlier changes. `note`: Write internal notes. `reply`: Reply to the submitter. `edit`: Edit answers and internal fields. `stage`: Change the stage. `assign`: Assign to anyone (an agent may always take a submission themselves). `files`: Add and remove files. `export`: Export. `delete`: Delete and restore. `run`: Run manual automations. `forms`: Manage forms and lists. `automations`: Manage automations and connections. `team`: Manage the team."
        },
        "forms": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Only these forms (keys). [] = every form."
        },
        "own_only": {
          "type": "boolean",
          "default": false,
          "description": "Sees only what is assigned to them."
        },
        "see_unassigned": {
          "type": "boolean",
          "default": true,
          "description": "With own_only: also sees unassigned submissions, to pick them up."
        },
        "hide_contacts": {
          "type": "boolean",
          "default": false,
          "description": "Numbers, e-mail addresses and answers of type phone or email are masked for this member."
        },
        "notify": {
          "type": "object",
          "properties": {
            "assigned": {
              "type": "boolean",
              "description": "E-mail them when a submission is assigned to them."
            },
            "created": {
              "type": "boolean",
              "description": "E-mail them for every new submission they may see."
            }
          }
        }
      },
      "description": "Any of these; what is left out stays. The owner's own row cannot be changed."
    },
    "SubmitAutomationTryRequest": {
      "type": "object",
      "properties": {
        "automation": {
          "$ref": "#/definitions/SubmitAutomationInput",
          "description": "The automation document to try; it need not be saved. The id of a saved automation (a number) is accepted in its place."
        },
        "submission": {
          "type": "string",
          "example": "QR-4HT9XC",
          "description": "A real submission to try it on: id or reference."
        },
        "call": {
          "type": "boolean",
          "default": false,
          "description": "true: http, openapi and mcp actions really call the outside system, so its answer and the save paths can be checked. false: their requests are built and shown, not sent."
        },
        "context": {
          "type": "object",
          "additionalProperties": true,
          "description": "What the trigger would know, when the automation reads it: {from, to, note} of a stage change, {button} of a pressed button, {note} of a note."
        }
      },
      "required": [
        "automation",
        "submission"
      ]
    },
    "SubmitGuideResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "guide": {
          "$ref": "#/definitions/SubmitGuide"
        }
      }
    },
    "SubmitSettingsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean",
          "description": "Submit-Info is switched on for the number."
        },
        "config": {
          "$ref": "#/definitions/SubmitSettings"
        },
        "code": {
          "type": "string",
          "example": "k3xbq9rtzp2mwv7",
          "description": "The number's public code: the part of every form and inbox address that names the number."
        },
        "links": {
          "type": "object",
          "properties": {
            "forms": {
              "type": "string",
              "description": "The base of the web forms: add / and a form's key."
            },
            "desk": {
              "type": "string",
              "description": "The staff inbox."
            },
            "wa_me": {
              "type": "string",
              "description": "Opens a WhatsApp chat with the number."
            }
          },
          "description": "The number's own addresses."
        }
      }
    },
    "SubmitSetupResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "dry_run": {
          "type": "boolean"
        },
        "applied": {
          "type": "object",
          "properties": {
            "lists": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "connections": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "automations": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "published": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "description": "What was written (a dry run: what would be), by key; automations by name; published: the forms now live on WhatsApp."
        },
        "note": {
          "type": "string"
        },
        "problems": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitProblem"
          },
          "example": [
            {
              "path": "forms[0].definition.steps[0].fields[0].list",
              "code": "unknown_list",
              "message": "There is no list called 'product'.",
              "fix": "Use the key of a list in this document or of the number: products."
            }
          ],
          "description": "Empty when the document is fine."
        }
      }
    },
    "SubmitPresetsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "presets": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitPreset"
          },
          "description": "Without ?key=."
        },
        "key": {
          "type": "string",
          "description": "With ?key= only."
        },
        "preset": {
          "$ref": "#/definitions/SubmitSetup",
          "description": "With ?key= only: that preset as a complete setup document."
        }
      }
    },
    "SubmitFormsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "forms": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitForm"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "SubmitFormResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "form": {
          "$ref": "#/definitions/SubmitForm"
        },
        "applied": {
          "type": "object",
          "additionalProperties": true,
          "description": "After POST /submit/forms with preset only: what the preset installed, as in the setup answer (lists, connections, forms, automations, published)."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SubmitFormSendResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "sent": {
          "type": "boolean",
          "description": "A WhatsApp message went out. false: outside the contact's 24 hour window, a form message went to them less than 2 minutes ago, or link_only."
        },
        "sent_flow": {
          "type": "boolean",
          "description": "true: it was the WhatsApp form. false with sent true: a message with a button to the web form."
        },
        "link": {
          "type": "string",
          "description": "The contact's personal web link to the form: they are known, and the prefill values are in it. Send it yourself when sent is false."
        },
        "session_id": {
          "type": "integer",
          "description": "This request to fill the form."
        },
        "to": {
          "type": "string",
          "description": "The contact, as it was understood."
        },
        "note": {
          "type": "string",
          "description": "What happened, and why nothing was sent when sent is false."
        }
      }
    },
    "SubmitListsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "lists": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitList"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "SubmitListResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "list": {
          "$ref": "#/definitions/SubmitList"
        }
      }
    },
    "SubmitDeletedResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "boolean"
        },
        "key": {
          "type": "string",
          "description": "A form, list or connection: the key that was deleted."
        },
        "id": {
          "type": "integer",
          "description": "An automation: the id that was deleted."
        },
        "archived": {
          "type": "boolean",
          "description": "A form with submissions: it was archived, not deleted (deleted is false then)."
        },
        "used_by": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list: the keys of the forms that still name it."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SubmissionDeletedResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "string",
          "example": "MR-7Q3M2A",
          "description": "The reference of the submission."
        },
        "id": {
          "type": "integer"
        },
        "erased": {
          "type": "boolean",
          "description": "true: its rows and files are gone for good."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SubmitMemberRemovedResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "integer",
          "example": 12,
          "description": "The id of the member who was removed."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SubmissionsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "submissions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Submission"
          }
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page, with the same filter and sort. Left out on the last page."
        },
        "count": {
          "type": "integer",
          "description": "How many are in this page."
        }
      }
    },
    "SubmissionResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "submission": {
          "$ref": "#/definitions/Submission"
        },
        "changed": {
          "type": "boolean",
          "description": "PATCH only. false: the submission already had these values."
        }
      }
    },
    "SubmissionEventResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "event": {
          "$ref": "#/definitions/SubmissionEvent"
        }
      }
    },
    "SubmissionReplyResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "sent": {
          "type": "boolean",
          "description": "The message went out now."
        },
        "held": {
          "type": "boolean",
          "description": "WhatsApp cannot take a normal message for this person right now: the reply is kept, they get a short notice, and the reply itself the moment they tap it or write to the number. The same as a reply from the Inbox."
        },
        "by": {
          "type": "string",
          "enum": [
            "whatsapp",
            "email"
          ],
          "description": "How it went: e-mail when the submitter left only an address, or WhatsApp could not be used."
        },
        "event": {
          "$ref": "#/definitions/SubmissionEvent"
        },
        "note": {
          "type": "string",
          "description": "Only when held."
        }
      }
    },
    "SubmissionFileResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "file": {
          "$ref": "#/definitions/SubmissionFile"
        }
      }
    },
    "SubmitRunResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "run": {
          "$ref": "#/definitions/SubmitRun"
        }
      }
    },
    "SubmitRunsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "runs": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitRun"
          }
        },
        "count": {
          "type": "integer"
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. Left out on the last page."
        }
      }
    },
    "SubmitMembersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "members": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitMember"
          }
        },
        "count": {
          "type": "integer"
        }
      }
    },
    "SubmitMemberResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "member": {
          "$ref": "#/definitions/SubmitMember"
        },
        "invite_link": {
          "type": "string",
          "description": "After an invitation: the link in the e-mail. It works for 14 days."
        },
        "email_sent": {
          "type": "boolean",
          "description": "After an invitation. false: the e-mail could not be sent, pass invite_link on yourself."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "SubmitAutomationsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "automations": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitAutomation"
          }
        }
      }
    },
    "SubmitAutomationResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "automation": {
          "$ref": "#/definitions/SubmitAutomation"
        }
      }
    },
    "SubmitConnectionsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "connections": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitConnection"
          }
        }
      }
    },
    "SubmitConnectionResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "connection": {
          "$ref": "#/definitions/SubmitConnection"
        },
        "functions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitConnectionFunction"
          },
          "description": "After a refresh."
        }
      }
    },
    "SubmitConnectionTestResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "ok": {
          "type": "boolean"
        },
        "stage": {
          "type": "string",
          "example": "response",
          "description": "Where the call ended, for example config (the connection cannot be used as saved), not_sent (refused before sending: a private address, the call limit), timeout, redirect, response (the system answered: status has its code)."
        },
        "status": {
          "type": "integer",
          "description": "The HTTP status of the outside system's answer. 0: no answer."
        },
        "error": {
          "type": "string"
        },
        "ms": {
          "type": "integer"
        }
      }
    },
    "SubmitConnectionFunctionsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "functions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SubmitConnectionFunction"
          }
        },
        "functions_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When they were last read. null: never (POST .../refresh)."
        }
      }
    },
    "SubmitReportResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "days": {
          "type": "integer",
          "description": "The range that was counted: submissions created in the last so many days."
        },
        "timezone": {
          "type": "string",
          "description": "The time zone by_day is cut in."
        },
        "open_now": {
          "type": "integer",
          "description": "Submissions in an open stage now."
        },
        "closed_avg_hours": {
          "type": "number",
          "nullable": true,
          "description": "Average hours from submission to a done or cancelled stage, of those closed in the range. null: none was closed."
        },
        "by_form": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "form": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              },
              "open": {
                "type": "integer"
              }
            }
          },
          "description": "Per form, most first: how many, and how many of them are still open."
        },
        "by_stage": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "form": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "status_kind": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              }
            }
          },
          "description": "Per form and stage key."
        },
        "by_day": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "day": {
                "type": "string",
                "example": "2026-11-13"
              },
              "count": {
                "type": "integer"
              }
            }
          },
          "description": "Per day of creation."
        },
        "by_assignee": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              },
              "open": {
                "type": "integer"
              }
            }
          },
          "description": "Per member; id 0 = not assigned."
        }
      }
    },
    "OptimizationSpec": {
      "type": "object",
      "description": "Marketing max price (Meta: 'max price'). Needs the WhatsApp account enrolled in Meta's max price feature (Marketing Messages API). Both fields null: back to rate card pricing. Replaces bid_spec (not accepted since 31 Jul 2026).",
      "required": [
        "bid_amount",
        "bid_strategy"
      ],
      "properties": {
        "bid_amount": {
          "type": "integer",
          "nullable": true,
          "example": 5000,
          "description": "Most WhatsApp may charge per 1,000 deliveries, in the smallest unit of the account's currency (5000 = USD 0.05 a message)."
        },
        "bid_strategy": {
          "type": "string",
          "nullable": true,
          "enum": [
            "LOWEST_COST_WITH_BID_CAP"
          ]
        },
        "bid_country_multiplier_overrides": {
          "type": "object",
          "additionalProperties": {
            "type": "number"
          },
          "example": {
            "IN": 1.2,
            "MX": 0.8
          },
          "description": "Country (ISO 3166-1 alpha-2) -> multiplier (above 0, at most 10), up to 240. Replaces the whole map; {} removes it."
        }
      }
    },
    "TemplateEditRequest": {
      "type": "object",
      "description": "Only what changes. components replace all components. An APPROVED template: at most 1 edit a day and 10 in 30 days, category fixed.",
      "properties": {
        "components": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "All components, in WhatsApp's format. A media header may use example.header_sample_url (a public link)."
        },
        "category": {
          "type": "string",
          "enum": [
            "MARKETING",
            "UTILITY",
            "AUTHENTICATION"
          ],
          "description": "Not for APPROVED templates."
        },
        "message_send_ttl_seconds": {
          "type": "integer",
          "description": "How long WhatsApp tries to deliver (Meta's ranges per category)."
        },
        "cta_url_link_tracking_opted_out": {
          "type": "boolean",
          "description": "true: no click tracking on URL buttons."
        },
        "parameter_format": {
          "type": "string",
          "enum": [
            "NAMED",
            "POSITIONAL"
          ]
        },
        "sub_category": {
          "type": "string",
          "example": "ORDER_STATUS"
        },
        "display_format": {
          "type": "string",
          "example": "ORDER_DETAILS"
        },
        "is_primary_device_delivery_only": {
          "type": "boolean"
        },
        "optimization_spec": {
          "$ref": "#/definitions/OptimizationSpec"
        },
        "allow_category_change": {
          "type": "boolean",
          "description": "Passed on; Meta ignores it since 9 Apr 2025."
        }
      }
    },
    "TemplateEditResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "template": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "previous_status": {
              "type": "string"
            }
          }
        },
        "changed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplateBulkDeleteRequest": {
      "type": "object",
      "description": "names (every language of each) or ids (one language each), not both. At most 100 template languages.",
      "properties": {
        "names": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 100
        },
        "ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 100
        }
      }
    },
    "TemplateBulkDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplateArchiveResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "archived": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "language": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            }
          },
          "description": "archive only."
        },
        "unarchived": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "language": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            }
          },
          "description": "unarchive only."
        },
        "failed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "language": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplateCompareResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "template": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          }
        },
        "with": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          }
        },
        "days": {
          "type": "integer"
        },
        "since": {
          "type": "string",
          "format": "date-time"
        },
        "until": {
          "type": "string",
          "format": "date-time"
        },
        "metrics": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "Meta's comparison as it comes: BLOCK_RATE (order), MESSAGE_SENDS, TOP_BLOCK_REASON, by template id."
        }
      }
    },
    "TemplateAuthUpsertRequest": {
      "type": "object",
      "required": [
        "languages"
      ],
      "description": "languages + otp_type (app2email builds the components), or languages + components (WhatsApp's own).",
      "properties": {
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "en_US",
            "es_ES",
            "fr"
          ]
        },
        "otp_type": {
          "type": "string",
          "enum": [
            "COPY_CODE",
            "ONE_TAP",
            "ZERO_TAP"
          ]
        },
        "add_security_recommendation": {
          "type": "boolean",
          "description": "Adds 'For your security, do not share this code.'"
        },
        "code_expiration_minutes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 90,
          "description": "Adds the expiry footer."
        },
        "supported_apps": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string"
              },
              "signature_hash": {
                "type": "string"
              }
            }
          },
          "description": "ONE_TAP and ZERO_TAP: 1 to 5 Android apps."
        },
        "zero_tap_terms_accepted": {
          "type": "boolean",
          "description": "ZERO_TAP: must be true."
        },
        "components": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "Instead of the fields above: BODY, FOOTER, BUTTONS in WhatsApp's format."
        },
        "message_send_ttl_seconds": {
          "type": "integer",
          "minimum": 30,
          "maximum": 900
        }
      }
    },
    "TemplateAuthUpsertResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "category": {
          "type": "string"
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "language": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplatePreviewsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "category": {
          "type": "string"
        },
        "previews": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "language": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "footer": {
                "type": "string"
              },
              "buttons": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "TemplateLibraryResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          },
          "description": "Meta's library templates as they come (name, language, category, topic, usecase, industry, header, body, body_params, buttons, id)."
        },
        "next_cursor": {
          "type": "string",
          "nullable": true
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplateInsightsEnableRequest": {
      "type": "object",
      "required": [
        "confirm"
      ],
      "properties": {
        "confirm": {
          "type": "boolean",
          "enum": [
            true
          ],
          "description": "Must be true: switching insights on cannot be undone."
        }
      }
    },
    "TemplateInsightsEnableResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TemplateInsightsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "since": {
          "type": "string",
          "format": "date"
        },
        "until": {
          "type": "string",
          "format": "date"
        },
        "product": {
          "type": "string",
          "enum": [
            "cloud_api",
            "marketing_messages"
          ]
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            }
          }
        },
        "data_points": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "template": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "template_id": {
                "type": "string"
              },
              "date": {
                "type": "string",
                "format": "date"
              },
              "sent": {
                "type": "integer"
              },
              "delivered": {
                "type": "integer"
              },
              "read": {
                "type": "integer"
              },
              "clicked": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                },
                "description": "Per button: {type, button_content, count}."
              },
              "cost": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                },
                "description": "{type: amount_spent | cost_per_delivered | cost_per_url_button_click, value}."
              }
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "TicketEvent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The event's id.",
          "example": 12
        },
        "slug": {
          "type": "string",
          "description": "The last part of the event's address.",
          "example": "summer-quiz"
        },
        "code": {
          "type": "string",
          "description": "The short code people can send in the WhatsApp chat to open this event.",
          "example": "EV-7H3KQ"
        },
        "name": {
          "type": "string",
          "example": "Summer Quiz"
        },
        "summary": {
          "type": "string",
          "description": "One line under the name (up to 160 characters)."
        },
        "description": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "description": "draft: not on sale yet. ended: no scheduled date is left.",
          "enum": [
            "draft",
            "published",
            "ended",
            "cancelled"
          ]
        },
        "sales": {
          "type": "string",
          "enum": [
            "on",
            "paused"
          ]
        },
        "visibility": {
          "type": "string",
          "description": "unlisted: not in the list of the number's events; the link works.",
          "enum": [
            "public",
            "unlisted"
          ]
        },
        "schedule": {
          "type": "string",
          "description": "single: one date. dates: several dates. slots: timed entry.",
          "enum": [
            "single",
            "dates",
            "slots"
          ]
        },
        "seating": {
          "type": "string",
          "description": "map: buyers pick seats on a seat plan.",
          "enum": [
            "none",
            "map"
          ]
        },
        "archived": {
          "type": "boolean"
        },
        "timezone": {
          "type": "string",
          "description": "IANA time zone of the event's times.",
          "example": "Australia/Sydney"
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217.",
          "example": "AUD"
        },
        "capacity": {
          "type": "integer",
          "description": "People per date. 0 = no limit. Not used with a seat plan."
        },
        "held_back": {
          "type": "integer",
          "description": "Places per date only the business's staff can sell."
        },
        "url": {
          "type": "string",
          "description": "The buyers' page of the event. It shows the event only while it is published."
        },
        "cover_url": {
          "type": "string",
          "description": "The first picture of the event, 800 pixels wide. Empty when it has none."
        },
        "settings": {
          "type": "object",
          "additionalProperties": true,
          "description": "The event's options with every default filled in: doors_min, sales_end, sales_end_min, place, venue {name, address, map, lat, lng, pin, note, hide_address}, online {url, note}, age, age_text, access_info, max_per_order, max_per_buyer, show_remaining, fee {ticket_minor, order_minor, show}, tax {rate, label, inclusive}, donation {enabled, amounts}, checkout {email}, names, questions, terms_text, terms_url, marketing_optin, seat {pick, no_single}, reminders, reminder_note, holder_changes, refund_policy, refund_days, refund_text, waitlist, door {opens_min, reentry, gates [{id, name, type_ids}]}, brand {color}, ticket_style. Amounts inside it (fee.ticket_minor, fee.order_minor, donation.amounts) are whole numbers in the smallest unit of the currency, as stored: the one place of this API where money is not a decimal number."
        },
        "from_price": {
          "type": "number",
          "description": "The lowest all-in price of a public ticket type. null when there is none, or it was not read.",
          "nullable": true
        },
        "from_price_label": {
          "type": "string"
        },
        "tickets_sold": {
          "type": "integer",
          "description": "Valid tickets of all dates (extras not counted).",
          "nullable": true
        },
        "dates_count": {
          "type": "integer",
          "description": "Dates that are scheduled.",
          "nullable": true
        },
        "next_date": {
          "$ref": "#/definitions/TicketDate",
          "nullable": true,
          "description": "The next scheduled date. null when there is none."
        },
        "seat_plan": {
          "type": "object",
          "nullable": true,
          "description": "null without a seat plan. Seat plans are drawn on the dashboard.",
          "properties": {
            "seats": {
              "type": "integer",
              "description": "Places of the plan."
            },
            "areas": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "capacity": {
                    "type": "integer"
                  }
                }
              },
              "description": "The standing areas of the plan."
            }
          }
        },
        "sales_start": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When buyers can start to buy. null = from the moment it is published."
        },
        "published": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When it was first published."
        },
        "ended": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "cancelled": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "cancel_reason": {
          "type": "string"
        },
        "created_by": {
          "type": "string",
          "description": "Who made it: a person of the business, or API key <name>."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        },
        "dates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketDate"
          },
          "description": "Only in answers with ONE event: its scheduled dates, soonest first, at most 50."
        },
        "dates_more": {
          "type": "boolean",
          "description": "Only with dates: there are more than 50; GET /tickets/events/{id}/dates pages through all of them."
        },
        "types": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketType"
          },
          "description": "Only in answers with ONE event: its ticket types that are not archived, in their order."
        },
        "problems": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Only in answers with ONE event that is a draft: what still stops publishing, one sentence each. Empty: it can be published."
        }
      },
      "description": "An event with its options and what is sold. Money is a number in the event's currency plus a label such as \"A$12.00\"."
    },
    "TicketDate": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The date's id.",
          "example": 31
        },
        "event_id": {
          "type": "integer",
          "description": "The event it belongs to.",
          "example": 12
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "description": "When it starts (UTC)."
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "description": "When it ends (UTC)."
        },
        "start_local": {
          "type": "string",
          "description": "The start as clock time in the event's time zone (yyyy-MM-ddTHH:mm).",
          "example": "2026-12-12T19:30"
        },
        "end_local": {
          "type": "string",
          "description": "The end as clock time in the event's time zone.",
          "example": "2026-12-12T21:30"
        },
        "label": {
          "type": "string",
          "description": "A short name of the date, eg Late show. Empty when it has none."
        },
        "capacity": {
          "type": "integer",
          "description": "How many people fit: the date's own limit, else the event's; with a seat plan the places of the plan. null = no limit.",
          "nullable": true
        },
        "sales": {
          "type": "string",
          "description": "paused: nothing is sold for this date right now.",
          "enum": [
            "on",
            "paused"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "ended",
            "cancelled"
          ]
        },
        "sold": {
          "type": "integer",
          "description": "Valid tickets (extras not counted). The five counts sold, people, held, left and checked_in are null inside webhook events, in the door list and in next_date of the events list.",
          "nullable": true
        },
        "people": {
          "type": "integer",
          "description": "The people those tickets admit (a group ticket admits several).",
          "nullable": true
        },
        "held": {
          "type": "integer",
          "description": "People in baskets right now.",
          "nullable": true
        },
        "left": {
          "type": "integer",
          "description": "People that can still be sold. null = no limit, or the counts were not read.",
          "nullable": true
        },
        "checked_in": {
          "type": "integer",
          "description": "People admitted at the door.",
          "nullable": true
        },
        "sold_out": {
          "type": "boolean",
          "description": "The date sold its last public ticket and no place has come back since."
        },
        "changed": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When the time or the venue last changed and ticket holders were told."
        },
        "cancelled": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When the date was cancelled."
        }
      },
      "description": "One date (session) of an event. A one-off event has exactly one. Also inside ticket.event.sold_out and ticket.event.cancelled."
    },
    "TicketType": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The ticket type's id.",
          "example": 44
        },
        "event_id": {
          "type": "integer",
          "example": 12
        },
        "name": {
          "type": "string",
          "example": "Adult"
        },
        "description": {
          "type": "string"
        },
        "role": {
          "type": "string",
          "description": "ticket: admits people. addon: an extra such as parking or a drink voucher, bought with a ticket.",
          "enum": [
            "ticket",
            "addon"
          ]
        },
        "status": {
          "type": "string",
          "description": "archived: offered nowhere any more; the tickets sold stay valid.",
          "enum": [
            "active",
            "archived"
          ]
        },
        "visibility": {
          "type": "string",
          "description": "hidden: buyers see it only with a code that unlocks it.",
          "enum": [
            "public",
            "hidden"
          ]
        },
        "sort": {
          "type": "integer",
          "description": "The place in the list, lowest first."
        },
        "price_mode": {
          "type": "string",
          "description": "choose: the buyer names the amount, from min_price.",
          "enum": [
            "fixed",
            "choose"
          ]
        },
        "price": {
          "type": "number",
          "description": "The price as the organiser typed it, in the event's currency.",
          "example": 12.0
        },
        "price_label": {
          "type": "string",
          "example": "A$12.00"
        },
        "price_all_in": {
          "type": "number",
          "description": "What a buyer pays for one, booking fee and tax included.",
          "example": 12.0
        },
        "price_all_in_label": {
          "type": "string",
          "example": "A$12.00"
        },
        "min_price": {
          "type": "number",
          "description": "price_mode choose: the least amount. 0 otherwise."
        },
        "admits": {
          "type": "integer",
          "description": "How many people one ticket admits (1 to 20)."
        },
        "quantity": {
          "type": "integer",
          "description": "How many can be sold per date. 0 = no limit of its own."
        },
        "pool_id": {
          "type": "integer",
          "description": "The shared capacity it draws from. 0 = none."
        },
        "opens_after": {
          "type": "integer",
          "description": "The ticket type that must sell out before this one goes on sale. 0 = none."
        },
        "needs": {
          "type": "integer",
          "description": "The ticket type that must be in the same order. 0 = none."
        },
        "needs_each": {
          "type": "boolean",
          "description": "true: one of `needs` for each of these."
        },
        "min_per_order": {
          "type": "integer"
        },
        "max_per_order": {
          "type": "integer",
          "description": "0 = the event's order limit."
        },
        "sales_start": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When its sale opens. null = with the event."
        },
        "sales_end": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When its sale ends. null = with the event's rule."
        },
        "sales_end_days": {
          "type": "integer",
          "description": "Its sale ends this many days before each date. 0 = not used."
        },
        "date_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "The dates it is sold for. [] = every date."
        },
        "door_note": {
          "type": "string",
          "description": "A note the door sees, eg Check student card."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "A ticket type (a named price) or an extra of an event."
    },
    "TicketOrder": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The order's id.",
          "example": 8812
        },
        "reference": {
          "type": "string",
          "example": "TK-7H3KQ9"
        },
        "status": {
          "type": "string",
          "description": "pending: a checkout that is not finished. expired: it was never paid or confirmed. confirmed: the tickets were issued.",
          "enum": [
            "pending",
            "confirmed",
            "partly_refunded",
            "refunded",
            "cancelled",
            "expired"
          ]
        },
        "kind": {
          "type": "string",
          "description": "online: paid by card. free: a free order. comp: complimentary. outside: paid outside app2email.",
          "enum": [
            "online",
            "free",
            "comp",
            "outside"
          ]
        },
        "channel": {
          "type": "string",
          "description": "Where it was made.",
          "enum": [
            "web",
            "whatsapp",
            "staff",
            "door",
            "api"
          ]
        },
        "source": {
          "type": "string",
          "description": "The src label of the link the buyer came through."
        },
        "event": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            }
          }
        },
        "date": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer"
            },
            "start": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "start_local": {
              "type": "string"
            },
            "label": {
              "type": "string"
            }
          },
          "description": "The date that was bought."
        },
        "buyer": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "contact": {
              "type": "string",
              "description": "The WhatsApp number in digits, or a business-scoped user id. Empty when unknown; erased-... after an erase."
            },
            "email": {
              "type": "string"
            },
            "no_whatsapp": {
              "type": "boolean",
              "description": "The buyer said they do not use WhatsApp."
            }
          }
        },
        "currency": {
          "type": "string",
          "example": "AUD"
        },
        "total": {
          "type": "number",
          "description": "What the buyer pays, in currency."
        },
        "total_label": {
          "type": "string",
          "example": "A$24.00"
        },
        "tickets_total": {
          "type": "number",
          "description": "The sum of the ticket prices."
        },
        "order_fee": {
          "type": "number"
        },
        "donation": {
          "type": "number"
        },
        "discount": {
          "type": "number",
          "description": "Information: already taken off tickets_total."
        },
        "fees": {
          "type": "number",
          "description": "Information: the booking fees inside total."
        },
        "tax": {
          "type": "number",
          "description": "Information: the tax inside total."
        },
        "refunded": {
          "type": "number"
        },
        "refunded_label": {
          "type": "string",
          "description": "Empty while nothing was refunded."
        },
        "ticket_count": {
          "type": "integer",
          "description": "Tickets of role ticket."
        },
        "people_count": {
          "type": "integer",
          "description": "The people they admit."
        },
        "addon_count": {
          "type": "integer"
        },
        "promo_code": {
          "type": "string"
        },
        "payment": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "description": "The online payment: the id of GET /payments/{id}. null for free, complimentary and outside orders.",
              "nullable": true
            },
            "method": {
              "type": "string",
              "description": "stripe, paypal, cash, bank, card_machine, other, or empty."
            },
            "note": {
              "type": "string",
              "description": "The note of a sale paid outside."
            }
          }
        },
        "comp_reason": {
          "type": "string",
          "description": "kind comp: guest, artist, press, sponsor, staff, prize or other."
        },
        "staff_note": {
          "type": "string",
          "description": "The business's internal note."
        },
        "created_by": {
          "type": "string",
          "description": "customer, a person of the business, or API key <name>."
        },
        "attention": {
          "type": "string",
          "description": "Not empty: the order needs a look. dispute: the buyer's bank opened a card dispute and the tickets are blocked.",
          "enum": [
            "",
            "refund_failed",
            "refund_outside",
            "refund_mismatch",
            "paid_twice",
            "dispute"
          ]
        },
        "close_reason": {
          "type": "string",
          "description": "Why it ended without tickets: unpaid, buyer_cancelled, staff_cancelled, late_payment, date_cancelled, event_cancelled or erased."
        },
        "refund_request": {
          "type": "object",
          "nullable": true,
          "description": "A refund the buyer asked for. null when there is none.",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "open",
                "refunded",
                "declined"
              ]
            },
            "reason": {
              "type": "string"
            },
            "at": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            }
          }
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "The answers given for the order: question id -> value."
        },
        "marketing_optin": {
          "type": "boolean"
        },
        "erased": {
          "type": "boolean",
          "description": "The buyer's details were erased on request."
        },
        "page_url": {
          "type": "string",
          "description": "The ticket page of this order. Anyone who has the link can open the tickets: treat it like a password and give it only to the buyer. Empty in webhook events and for an erased order."
        },
        "expires": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "pending: until when it can be paid or confirmed."
        },
        "confirmed": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "When the tickets were issued."
        },
        "cancelled": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "refunded_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        },
        "tickets": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketIssued"
          },
          "description": "Every ticket of the order, any status. In GET /tickets/orders only with tickets=true."
        }
      },
      "description": "A ticket order: the buyer, the money and, where asked for, its tickets. Money is a number in the order's currency plus a label. Also inside ticket.order.confirmed and ticket.order.refunded, there with an empty page_url."
    },
    "TicketIssued": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The ticket's id.",
          "example": 501
        },
        "order_id": {
          "type": "integer",
          "example": 8812
        },
        "order_reference": {
          "type": "string",
          "example": "TK-7H3KQ9"
        },
        "event_id": {
          "type": "integer",
          "example": 12
        },
        "date_id": {
          "type": "integer",
          "description": "The date the ticket is for.",
          "example": 31
        },
        "type_id": {
          "type": "integer",
          "example": 44
        },
        "type_name": {
          "type": "string",
          "description": "The ticket type's name as it was sold.",
          "example": "Adult"
        },
        "role": {
          "type": "string",
          "enum": [
            "ticket",
            "addon"
          ]
        },
        "seq": {
          "type": "integer",
          "description": "1..n inside the order."
        },
        "status": {
          "type": "string",
          "description": "valid and blocked tickets hold a place; refunded, cancelled and transferred (passed on) are final.",
          "enum": [
            "valid",
            "blocked",
            "refunded",
            "cancelled",
            "transferred"
          ]
        },
        "holder_name": {
          "type": "string"
        },
        "answers": {
          "type": "object",
          "additionalProperties": true,
          "description": "The answers given for this ticket: question id -> value."
        },
        "seat": {
          "type": "object",
          "nullable": true,
          "description": "null without a seat.",
          "properties": {
            "key": {
              "type": "string",
              "description": "The key of the seat in the seat plan."
            },
            "label": {
              "type": "string",
              "example": "Stalls, Row C, Seat 7"
            },
            "section": {
              "type": "string"
            },
            "row": {
              "type": "string"
            },
            "seat": {
              "type": "string"
            },
            "table": {
              "type": "string"
            }
          }
        },
        "admits": {
          "type": "integer"
        },
        "check_in": {
          "$ref": "#/definitions/TicketCheckIn"
        },
        "currency": {
          "type": "string"
        },
        "price": {
          "type": "number",
          "description": "What was paid for this ticket, all in: what a refund of it returns."
        },
        "price_label": {
          "type": "string"
        },
        "face": {
          "type": "number",
          "description": "The all-in list price before a discount."
        },
        "refunded": {
          "type": "number"
        },
        "refunded_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "block_reason": {
          "type": "string",
          "description": "Why staff blocked it. A disputed payment reads Payment disputed."
        },
        "passed_on": {
          "type": "boolean",
          "description": "true: the ticket was made when a holder passed a ticket on."
        },
        "replaces_id": {
          "type": "integer",
          "description": "The ticket this one replaced. 0 = none."
        },
        "replaced_by_id": {
          "type": "integer",
          "description": "The ticket that replaced this one. 0 = none."
        },
        "page_url": {
          "type": "string",
          "description": "The ticket page of this ticket. Anyone who has the link can open the ticket: treat it like a password and give it only to the buyer. Empty in webhook events, for an erased order and for a ticket that is no longer valid."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        },
        "buyer": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "contact": {
              "type": "string"
            },
            "email": {
              "type": "string"
            }
          },
          "description": "Only in the rows of GET /tickets/issued: who bought it."
        }
      },
      "description": "One ticket (or one extra) of an order, with its check-in state. The ticket code, the text of its QR code, is never in an answer. Also inside ticket.checked_in and ticket.passed_on, there with an empty page_url."
    },
    "TicketPromoCode": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "example": 7
        },
        "code": {
          "type": "string",
          "example": "EARLY10"
        },
        "kind": {
          "type": "string",
          "enum": [
            "percent",
            "amount"
          ]
        },
        "value": {
          "type": "number",
          "description": "kind percent: 1 to 100. kind amount: an amount in currency."
        },
        "currency": {
          "type": "string",
          "description": "kind amount: the currency of value. The code only works for events in it."
        },
        "event_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "[] = every event."
        },
        "type_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "[] = every ticket type."
        },
        "unlocks": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "The hidden ticket types this code opens."
        },
        "starts": {
          "type": "string",
          "description": "Empty, or the first day it works (YYYY-MM-DD)."
        },
        "ends": {
          "type": "string",
          "description": "Empty, or the last day it works (YYYY-MM-DD)."
        },
        "limit": {
          "type": "integer",
          "description": "How often it can be used. 0 = no limit."
        },
        "limit_unit": {
          "type": "string",
          "description": "What limit counts.",
          "enum": [
            "orders",
            "tickets"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "batch": {
          "type": "string",
          "description": "The name of the batch, for codes made many at a time on the dashboard."
        },
        "uses": {
          "type": "object",
          "properties": {
            "orders": {
              "type": "integer"
            },
            "tickets": {
              "type": "integer"
            }
          },
          "description": "The orders that used it and the tickets it was applied to."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "updated": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "A promo code (a discount) or an access code (it unlocks hidden ticket types), with how often it was used."
    },
    "TicketWaitlistEntry": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "example": 77
        },
        "event_id": {
          "type": "integer",
          "example": 12
        },
        "date_id": {
          "type": "integer",
          "example": 31
        },
        "type_id": {
          "type": "integer",
          "description": "The ticket type they wait for. 0 = any."
        },
        "name": {
          "type": "string"
        },
        "contact": {
          "type": "string",
          "description": "The WhatsApp number in digits, or a business-scoped user id. Empty when they left an email address only."
        },
        "email": {
          "type": "string"
        },
        "quantity": {
          "type": "integer"
        },
        "status": {
          "type": "string",
          "description": "notified: they were told a place is free. converted: they bought.",
          "enum": [
            "waiting",
            "notified",
            "converted",
            "removed",
            "expired"
          ]
        },
        "notified": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "notify_count": {
          "type": "integer"
        },
        "order_id": {
          "type": "integer",
          "description": "The order they made. 0 = none."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "Someone waiting for a place on a sold-out date. Also inside ticket.waitlist.joined."
    },
    "TicketCheckIn": {
      "type": "object",
      "properties": {
        "people": {
          "type": "integer",
          "description": "People admitted so far (0 to admits). Above 0 = checked in."
        },
        "inside": {
          "type": "integer",
          "description": "People inside now, for events that count people leaving."
        },
        "entries": {
          "type": "integer",
          "description": "Accepted scans on the way in."
        },
        "first_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "last_out_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "gate": {
          "type": "string",
          "description": "The id of the entrance of the last scan."
        }
      },
      "description": "The check-in state of a ticket."
    },
    "TicketAvailability": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "event": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "sales": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "description": "The page where buyers buy."
            }
          }
        },
        "date": {
          "$ref": "#/definitions/TicketDate"
        },
        "on_sale": {
          "type": "boolean",
          "description": "Buyers can buy for this date now."
        },
        "closed": {
          "type": "string",
          "description": "Empty, or why the date takes no order from anyone.",
          "enum": [
            "",
            "cancelled",
            "ended"
          ]
        },
        "sold_out": {
          "type": "boolean"
        },
        "max_per_order": {
          "type": "integer",
          "description": "The most tickets one order may hold."
        },
        "types": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type_id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "enum": [
                  "ticket",
                  "addon"
                ]
              },
              "visibility": {
                "type": "string",
                "enum": [
                  "public",
                  "hidden"
                ]
              },
              "state": {
                "type": "string",
                "description": "How a buyer meets the type now. waiting: it opens when another type sells out. hidden: only with a code.",
                "enum": [
                  "on_sale",
                  "sold_out",
                  "not_yet",
                  "ended",
                  "waiting",
                  "hidden"
                ]
              },
              "left": {
                "type": "integer",
                "description": "How many are left. null = nothing limits it.",
                "nullable": true
              },
              "max": {
                "type": "integer",
                "description": "The most one order may take of it now."
              },
              "price": {
                "type": "number",
                "description": "The all-in price of one; for price_mode choose the least amount."
              },
              "price_label": {
                "type": "string"
              },
              "sales_end": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "When its sale ends."
              }
            }
          },
          "description": "Every active ticket type and extra, hidden ones too. Archived ones never."
        }
      },
      "description": "What is on sale for one date of an event."
    },
    "TicketStats": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "event_id": {
          "type": "integer"
        },
        "date_id": {
          "type": "integer",
          "description": "null: all dates of the event.",
          "nullable": true
        },
        "currency": {
          "type": "string"
        },
        "orders": {
          "type": "integer",
          "description": "Confirmed orders."
        },
        "sold": {
          "type": "integer",
          "description": "People on valid tickets."
        },
        "held": {
          "type": "integer",
          "description": "People in baskets right now."
        },
        "left": {
          "type": "integer",
          "description": "People that can still be sold. null = no limit.",
          "nullable": true
        },
        "capacity": {
          "type": "integer",
          "description": "null = no limit.",
          "nullable": true
        },
        "checked_in": {
          "type": "integer",
          "description": "People admitted."
        },
        "money": {
          "type": "object",
          "properties": {
            "gross": {
              "type": "number"
            },
            "discounts": {
              "type": "number"
            },
            "fees": {
              "type": "number"
            },
            "tax": {
              "type": "number"
            },
            "donations": {
              "type": "number"
            },
            "refunded": {
              "type": "number"
            },
            "net": {
              "type": "number"
            },
            "net_label": {
              "type": "string",
              "example": "A$996.00"
            }
          },
          "description": "In the event's currency."
        },
        "by_type": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type_id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "role": {
                "type": "string"
              },
              "sold": {
                "type": "integer",
                "description": "Valid tickets or extras of this type."
              },
              "checked_in": {
                "type": "integer"
              },
              "gross": {
                "type": "number"
              }
            }
          }
        },
        "by_channel": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string"
              },
              "orders": {
                "type": "integer"
              },
              "tickets": {
                "type": "integer"
              },
              "gross": {
                "type": "number"
              }
            }
          }
        },
        "by_code": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "orders": {
                "type": "integer"
              },
              "tickets": {
                "type": "integer"
              },
              "discount": {
                "type": "number"
              }
            }
          }
        }
      },
      "description": "Sales and check-in figures of an event, or of one of its dates."
    },
    "TicketDoorList": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "date": {
          "$ref": "#/definitions/TicketDate",
          "description": "The date, without the five counts."
        },
        "counts": {
          "type": "object",
          "properties": {
            "sold": {
              "type": "integer"
            },
            "in": {
              "type": "integer"
            },
            "to_come": {
              "type": "integer"
            }
          },
          "description": "People: sold, inside or admitted, still to come."
        },
        "tickets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "code_sha256": {
                "type": "string",
                "description": "Lower-case hex SHA-256 of the text in the ticket's QR code."
              },
              "status": {
                "type": "string",
                "enum": [
                  "valid",
                  "blocked",
                  "refunded",
                  "cancelled",
                  "transferred"
                ]
              },
              "type_id": {
                "type": "integer"
              },
              "type_name": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "enum": [
                  "ticket",
                  "addon"
                ]
              },
              "holder_name": {
                "type": "string"
              },
              "seat_label": {
                "type": "string"
              },
              "admits": {
                "type": "integer"
              },
              "check_in": {
                "$ref": "#/definitions/TicketCheckIn"
              },
              "door_note": {
                "type": "string"
              },
              "id_check": {
                "type": "string",
                "description": "Empty, 18 or 21: the age to check at the door."
              },
              "order_reference": {
                "type": "string"
              },
              "passed_on": {
                "type": "boolean"
              },
              "answers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  }
                },
                "description": "Only the answers the organiser marked to show at the door."
              }
            }
          },
          "description": "One row per ticket. After a since, also tickets that stopped being valid: their status says so."
        },
        "gone": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Ids that are no longer tickets of this date since `since`: moved to another date, or erased."
        },
        "cursor": {
          "type": "string",
          "description": "Send it as since: for the next page while more is true, later for what changed."
        },
        "more": {
          "type": "boolean",
          "description": "Another page is waiting now."
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        },
        "note": {
          "type": "string",
          "description": "Only for a date with more than 20,000 tickets: its door list is not sent."
        }
      },
      "description": "The tickets of one date for a scanner of your own. No contact, email or money."
    },
    "TicketSettings": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "available": {
          "type": "boolean",
          "description": "false: ticket sales are not open for this number yet. Every other ticket call then answers 403 tickets_not_enabled."
        },
        "configured": {
          "type": "boolean",
          "description": "The number has ticket settings."
        },
        "enabled": {
          "type": "boolean",
          "description": "Ticket sales are switched on."
        },
        "selling": {
          "type": "boolean",
          "description": "Tickets are sold now: available, switched on, and in the plan."
        },
        "why": {
          "type": "string",
          "description": "Empty when selling, else why not.",
          "enum": [
            "",
            "tables_missing",
            "no_config",
            "removed",
            "off",
            "plan"
          ]
        },
        "events_url": {
          "type": "string",
          "description": "The page that lists the number's events."
        },
        "currency": {
          "type": "string",
          "description": "The currency new events start with."
        },
        "timezone": {
          "type": "string",
          "description": "The time zone new events start with."
        },
        "payments": {
          "type": "object",
          "properties": {
            "stripe": {
              "type": "boolean"
            },
            "paypal": {
              "type": "boolean"
            }
          },
          "description": "The business's own payment providers that can take a ticket payment."
        },
        "config": {
          "type": "object",
          "additionalProperties": true,
          "description": "The number's ticket settings with every default filled in. Sections: organiser {name, email, phone}, hold_minutes (5 to 30), notify {sale, email}, brand {logo, color, background, hide_powered}, ticket_style {layout, accent, background, text, image, image_as, logo, font, fields, footer}, wa {keywords, intro_text, cta, mine_keywords, send_pdf, texts}, privacy {retention_days, url}, texts. texts and wa.texts hold one wording per key (the sentences buyers read on the pages and in the chat); the example shows two of each."
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      },
      "description": "The ticket settings of the number and whether ticket sales are switched on."
    },
    "TicketEventCreateRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 80,
          "example": "Summer Quiz"
        },
        "start": {
          "type": "string",
          "description": "In the future. Local time in the number's time zone (2026-12-12T19:30) or ISO 8601 with an offset.",
          "example": "2026-12-12T19:30"
        },
        "price": {
          "type": "number",
          "description": "The price of the one ticket type, in the number's currency. 0 or left out: a free event.",
          "minimum": 0,
          "default": 0,
          "example": 12
        }
      },
      "required": [
        "name",
        "start"
      ]
    },
    "TicketEventPatchRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 80
        },
        "summary": {
          "type": "string",
          "maxLength": 160
        },
        "description": {
          "type": "string",
          "maxLength": 5000
        },
        "visibility": {
          "type": "string",
          "enum": [
            "public",
            "unlisted"
          ]
        },
        "sales": {
          "type": "string",
          "enum": [
            "on",
            "paused"
          ]
        },
        "capacity": {
          "type": "integer",
          "description": "People per date. 0 = no limit.",
          "minimum": 0,
          "maximum": 100000
        },
        "held_back": {
          "type": "integer",
          "description": "Places per date only staff can sell (0 to capacity).",
          "minimum": 0
        },
        "timezone": {
          "type": "string",
          "description": "An IANA time zone. The clock times of the coming dates stay."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217. Refused once the event has an order."
        },
        "sales_start": {
          "type": "string",
          "description": "Local time in the event's time zone (2026-12-12T19:30) or ISO 8601 with an offset (2026-12-12T19:30:00+11:00). null = from the moment it is published.",
          "nullable": true
        },
        "slug": {
          "type": "string",
          "description": "3 to 60 characters of a-z, 0-9 and -. Only until the first publish."
        },
        "settings": {
          "type": "object",
          "additionalProperties": true,
          "description": "Options to change: doors_min, sales_end, sales_end_min, place, venue {name, address, map, lat, lng, pin, note, hide_address}, online {url, note}, age, age_text, access_info, max_per_order, max_per_buyer, show_remaining, fee {ticket_minor, order_minor, show}, tax {rate, label, inclusive}, donation {enabled, amounts}, checkout {email}, names, questions, terms_text, terms_url, marketing_optin, seat {pick, no_single}, reminders, reminder_note, holder_changes, refund_policy, refund_days, refund_text, waitlist, door {opens_min, reentry, gates [{id, name, type_ids}]}, brand {color}, ticket_style. A key sent replaces the stored key; the others stay. Amounts are in the smallest unit of the currency, as GET shows them."
        },
        "notify": {
          "type": "boolean",
          "description": "true: tell ticket holders when the venue changed.",
          "default": false
        }
      },
      "description": "Any of these; what is left out stays."
    },
    "TicketCancelRequest": {
      "type": "object",
      "properties": {
        "refund": {
          "type": "string",
          "description": "all: everything paid goes back. prices: the ticket prices without booking fees and donations. none: the tickets are voided and no money moves.",
          "enum": [
            "all",
            "prices",
            "none"
          ]
        },
        "reason": {
          "type": "string",
          "description": "Told to the ticket holders.",
          "maxLength": 200
        },
        "notify": {
          "type": "boolean",
          "description": "false: do not tell the ticket holders.",
          "default": true
        },
        "confirm": {
          "type": "string",
          "description": "Must be the word CANCEL.",
          "enum": [
            "CANCEL"
          ]
        }
      },
      "required": [
        "refund",
        "confirm"
      ]
    },
    "TicketDateRequest": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "Needed for a new date, in the future. Local time in the event's time zone (2026-12-12T19:30) or ISO 8601 with an offset (2026-12-12T19:30:00+11:00).",
          "example": "2026-12-19T19:30"
        },
        "end": {
          "type": "string",
          "description": "After start, at most 31 days later. Default for a new date: 120 minutes after start."
        },
        "label": {
          "type": "string",
          "maxLength": 30,
          "example": "Late show"
        },
        "capacity": {
          "type": "integer",
          "description": "-1 = the event's (the default of a new date), 0 = no limit, else people.",
          "minimum": -1,
          "maximum": 100000
        },
        "sales": {
          "type": "string",
          "description": "Only when changing a date.",
          "enum": [
            "on",
            "paused"
          ]
        },
        "notify": {
          "type": "boolean",
          "description": "Only when changing a date. true: tell ticket holders about a new time.",
          "default": false
        }
      }
    },
    "TicketTypeRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Needed for a new ticket type.",
          "maxLength": 30,
          "example": "Child"
        },
        "price": {
          "type": "number",
          "description": "In the event's currency, with at most its decimals. Default 0.",
          "minimum": 0,
          "example": 6
        },
        "role": {
          "type": "string",
          "description": "Default ticket.",
          "enum": [
            "ticket",
            "addon"
          ]
        },
        "description": {
          "type": "string",
          "maxLength": 300
        },
        "visibility": {
          "type": "string",
          "description": "Default public.",
          "enum": [
            "public",
            "hidden"
          ]
        },
        "price_mode": {
          "type": "string",
          "description": "Default fixed.",
          "enum": [
            "fixed",
            "choose"
          ]
        },
        "min_price": {
          "type": "number",
          "description": "price_mode choose: the least amount. Default 0.",
          "minimum": 0
        },
        "admits": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 1
        },
        "quantity": {
          "type": "integer",
          "description": "0 = no limit of its own.",
          "minimum": 0,
          "maximum": 100000,
          "default": 0
        },
        "pool_id": {
          "type": "integer",
          "description": "A pool of the same event. 0 = none.",
          "default": 0
        },
        "opens_after": {
          "type": "integer",
          "description": "Another ticket type of the same event. 0 = none.",
          "default": 0
        },
        "needs": {
          "type": "integer",
          "description": "Another ticket type of the same event. 0 = none.",
          "default": 0
        },
        "needs_each": {
          "type": "boolean",
          "default": false
        },
        "min_per_order": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "default": 1
        },
        "max_per_order": {
          "type": "integer",
          "description": "0 = the event's order limit.",
          "minimum": 0,
          "maximum": 50,
          "default": 0
        },
        "sales_start": {
          "type": "string",
          "description": "Local time in the event's time zone (2026-12-12T19:30) or ISO 8601 with an offset (2026-12-12T19:30:00+11:00). null = with the event.",
          "nullable": true
        },
        "sales_end": {
          "type": "string",
          "description": "Local time in the event's time zone (2026-12-12T19:30) or ISO 8601 with an offset (2026-12-12T19:30:00+11:00). null = with the event's rule.",
          "nullable": true
        },
        "sales_end_days": {
          "type": "integer",
          "minimum": 0,
          "maximum": 60,
          "default": 0
        },
        "date_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Dates of the same event. [] = every date."
        },
        "door_note": {
          "type": "string",
          "maxLength": 80
        },
        "sort": {
          "type": "integer",
          "description": "Default: last."
        },
        "status": {
          "type": "string",
          "description": "Only when changing a ticket type.",
          "enum": [
            "active",
            "archived"
          ]
        }
      }
    },
    "TicketOrderCreateRequest": {
      "type": "object",
      "properties": {
        "event_id": {
          "type": "string",
          "description": "The event: its id, its slug or its code (EV-XXXXX).",
          "example": "summer-quiz"
        },
        "date_id": {
          "type": "integer",
          "description": "Needed when the event has more than one scheduled date."
        },
        "kind": {
          "type": "string",
          "description": "comp: complimentary tickets, every price 0. outside: a sale paid outside app2email (cash, a bank transfer, a card machine); the prices are recorded, no money is taken.",
          "enum": [
            "comp",
            "outside"
          ]
        },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type_id": {
                "type": "integer"
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50,
                "default": 1
              },
              "price": {
                "type": "number",
                "description": "Only for a ticket type whose buyer chooses the price: the amount for one, in the event's currency.",
                "minimum": 0
              },
              "seat_keys": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Seats of the seat plan to take. Their count replaces quantity. Left out on an event with a seat plan: the best free seats.",
                "maxItems": 50
              },
              "area": {
                "type": "string",
                "description": "The key of a standing area, for a ticket type sold there."
              }
            },
            "required": [
              "type_id"
            ]
          },
          "description": "What to issue: one entry per ticket type.",
          "minItems": 1,
          "maxItems": 40
        },
        "buyer": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "maxLength": 80
            },
            "contact": {
              "type": "string",
              "description": "A WhatsApp number with country code, digits only, or a business-scoped user id.",
              "example": "61412345678"
            },
            "email": {
              "type": "string",
              "format": "email"
            }
          },
          "description": "Who gets the tickets. All optional."
        },
        "holder_names": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "One name per ticket, in the order of items. Empty or left out: the buyer's name.",
          "maxItems": 50
        },
        "comp_reason": {
          "type": "string",
          "description": "kind comp.",
          "enum": [
            "guest",
            "artist",
            "press",
            "sponsor",
            "staff",
            "prize",
            "other"
          ],
          "default": "guest"
        },
        "payment_method": {
          "type": "string",
          "description": "kind outside.",
          "enum": [
            "cash",
            "bank",
            "card_machine",
            "other"
          ],
          "default": "other"
        },
        "payment_note": {
          "type": "string",
          "description": "kind outside: a note about the payment.",
          "maxLength": 200
        },
        "note": {
          "type": "string",
          "description": "An internal note on the order.",
          "maxLength": 2000
        },
        "notify": {
          "type": "boolean",
          "description": "false: do not send the tickets to the buyer.",
          "default": true
        },
        "check_in_now": {
          "type": "boolean",
          "description": "true: check every ticket in at once (a sale at the door).",
          "default": false
        },
        "gate": {
          "type": "string",
          "description": "With check_in_now: the id of the entrance. Default: the event's first."
        }
      },
      "required": [
        "event_id",
        "kind",
        "items"
      ]
    },
    "TicketRefundRequest": {
      "type": "object",
      "properties": {
        "ticket_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Tickets of this order. Left out or []: every valid ticket of the order.",
          "maxItems": 200
        },
        "what": {
          "type": "string",
          "description": "all: everything paid for the tickets. prices: without booking fees and donations.",
          "enum": [
            "all",
            "prices"
          ],
          "default": "all"
        },
        "money": {
          "type": "string",
          "description": "provider: back through the business's own Stripe or PayPal account. recorded: the money was handed back outside. outside: the business refunded it at Stripe or PayPal itself. none: cancel without a refund. Left out: provider for an online order, recorded for a sale paid outside, none for free and complimentary tickets.",
          "enum": [
            "provider",
            "recorded",
            "outside",
            "none"
          ]
        },
        "reason": {
          "type": "string",
          "maxLength": 200
        },
        "notify": {
          "type": "boolean",
          "description": "false: do not tell the buyer.",
          "default": true
        }
      },
      "description": "Every key is optional: no body refunds the whole order."
    },
    "TicketVoidRequest": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "maxLength": 200
        },
        "notify": {
          "type": "boolean",
          "description": "true: tell the buyer.",
          "default": false
        }
      },
      "description": "Every key is optional."
    },
    "TicketCheckInRequest": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The text of the ticket's QR code. A link or other text around it is fine. Needs date_id.",
          "maxLength": 300
        },
        "ticket_id": {
          "type": "integer",
          "description": "The ticket's id, instead of code."
        },
        "date_id": {
          "type": "integer",
          "description": "The date the person is entering. Needed with code; with ticket_id it defaults to the ticket's own date."
        },
        "direction": {
          "type": "string",
          "description": "out: check out, for events that count people leaving.",
          "enum": [
            "in",
            "out"
          ],
          "default": "in"
        },
        "people": {
          "type": "integer",
          "description": "For a group ticket: how many people enter now. 0 = everyone who is not in yet.",
          "minimum": 0,
          "maximum": 20,
          "default": 0
        },
        "gate": {
          "type": "string",
          "description": "The id of the entrance, one of the event's settings.door.gates. Default: the first."
        },
        "force": {
          "type": "boolean",
          "description": "true: admit although it is too early, too late or the wrong entrance.",
          "default": false
        }
      },
      "description": "Exactly one of code and ticket_id."
    },
    "TicketCodeRequest": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Needed for a new code; it cannot be changed later. 3 to 20 characters of A-Z, 0-9, _ and -.",
          "example": "EARLY10"
        },
        "kind": {
          "type": "string",
          "description": "Default percent.",
          "enum": [
            "percent",
            "amount"
          ]
        },
        "value": {
          "type": "number",
          "description": "kind percent: a whole number from 1 to 100. kind amount: an amount in currency. 0 only for a code that unlocks ticket types.",
          "example": 10
        },
        "currency": {
          "type": "string",
          "description": "kind amount. Default: the currency new events of the number start with."
        },
        "event_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Events of this number. Default []: every event."
        },
        "type_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Ticket types of this number. Default []: every ticket type."
        },
        "unlocks": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Hidden ticket types of this number that the code opens."
        },
        "starts": {
          "type": "string",
          "description": "Empty or YYYY-MM-DD."
        },
        "ends": {
          "type": "string",
          "description": "Empty or YYYY-MM-DD.",
          "example": "2026-12-01"
        },
        "limit": {
          "type": "integer",
          "description": "0 = no limit.",
          "minimum": 0,
          "maximum": 100000,
          "default": 0
        },
        "limit_unit": {
          "type": "string",
          "description": "Default orders.",
          "enum": [
            "orders",
            "tickets"
          ]
        },
        "enabled": {
          "type": "boolean",
          "default": true
        }
      }
    },
    "TicketSettingsRequest": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Switch ticket sales on or off."
        },
        "config": {
          "type": "object",
          "additionalProperties": true,
          "description": "Whole sections of the settings: organiser {name, email, phone}, hold_minutes (5 to 30), notify {sale, email}, brand {logo, color, background, hide_powered}, ticket_style {layout, accent, background, text, image, image_as, logo, font, fields, footer}, wa {keywords, intro_text, cta, mine_keywords, send_pdf, texts}, privacy {retention_days, url}, texts. A section sent replaces the stored section; the others stay."
        }
      },
      "description": "enabled, config, or both."
    },
    "TicketEventResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "event": {
          "$ref": "#/definitions/TicketEvent"
        },
        "started": {
          "type": "boolean",
          "description": "Only after a cancel: the refunds run in the background."
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketEventsResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketEvent"
          },
          "description": "Newest first, without dates, types and problems."
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. null on the last page.",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        }
      }
    },
    "TicketDateResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "date": {
          "$ref": "#/definitions/TicketDate"
        },
        "started": {
          "type": "boolean",
          "description": "Only after a cancel: the refunds run in the background."
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketDatesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "dates": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketDate"
          },
          "description": "Soonest first, with the five counts."
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. null on the last page.",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        },
        "timezone": {
          "type": "string",
          "description": "The event's time zone."
        }
      }
    },
    "TicketTypeResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "type": {
          "$ref": "#/definitions/TicketType"
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketTypesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "types": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketType"
          },
          "description": "In their order."
        },
        "currency": {
          "type": "string"
        }
      }
    },
    "TicketOrderResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "order": {
          "$ref": "#/definitions/TicketOrder"
        },
        "sent": {
          "type": "boolean",
          "description": "Only after an order was made: a delivery to the buyer was started."
        },
        "refunded": {
          "type": "number",
          "description": "Only after a refund: what this call refunded."
        },
        "refunded_label": {
          "type": "string"
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketOrdersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "orders": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketOrder"
          },
          "description": "Newest first."
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. null on the last page.",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        }
      }
    },
    "TicketIssuedResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "ticket": {
          "$ref": "#/definitions/TicketIssued"
        },
        "order": {
          "type": "object",
          "additionalProperties": true,
          "description": "GET /tickets/issued/{id}: the order's id, reference, status and buyer. After a void: the whole TicketOrder with its tickets.",
          "properties": {
            "id": {
              "type": "integer"
            },
            "reference": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "buyer": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "contact": {
                  "type": "string"
                },
                "email": {
                  "type": "string"
                }
              }
            }
          }
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketsIssuedResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "tickets": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketIssued"
          },
          "description": "By id, each with buyer."
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. null on the last page.",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        }
      }
    },
    "TicketCheckInResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "result": {
          "type": "string",
          "description": "ok: admitted (or checked out). Every other value is a refusal.",
          "enum": [
            "ok",
            "already_in",
            "not_inside",
            "unknown",
            "refunded",
            "cancelled",
            "transferred",
            "blocked",
            "wrong_event",
            "wrong_date",
            "wrong_gate",
            "too_early",
            "too_late"
          ]
        },
        "admitted": {
          "type": "boolean",
          "description": "result is ok."
        },
        "people": {
          "type": "integer",
          "description": "People admitted or checked out by this call."
        },
        "check_in": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "description": "The check-in's id: the handle for the undo. 0 when nothing was recorded."
            },
            "at": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "direction": {
              "type": "string",
              "enum": [
                "in",
                "out"
              ]
            },
            "gate": {
              "type": "string"
            },
            "forced": {
              "type": "boolean"
            }
          }
        },
        "ticket": {
          "$ref": "#/definitions/TicketIssued",
          "nullable": true,
          "description": "The ticket after the scan. null for result unknown."
        },
        "first": {
          "type": "object",
          "nullable": true,
          "description": "result already_in: the earlier admission. null otherwise.",
          "properties": {
            "at": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            },
            "gate": {
              "type": "string"
            },
            "by": {
              "type": "string"
            }
          }
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketCheckInUndoResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "undone": {
          "type": "boolean"
        },
        "ticket": {
          "$ref": "#/definitions/TicketIssued",
          "nullable": true,
          "description": "The ticket after the undo."
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "TicketCodeResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "code": {
          "$ref": "#/definitions/TicketPromoCode"
        }
      }
    },
    "TicketCodesResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "codes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketPromoCode"
          },
          "description": "By id."
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. null on the last page.",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        }
      }
    },
    "TicketCodeDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "integer",
          "description": "The id of the deleted code."
        }
      }
    },
    "TicketWaitlistResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "entries": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TicketWaitlistEntry"
          },
          "description": "In the order they joined."
        },
        "next_cursor": {
          "type": "string",
          "description": "Pass it as cursor for the next page. null on the last page.",
          "nullable": true
        },
        "count": {
          "type": "integer",
          "description": "How many rows this answer has."
        }
      }
    },
    "TicketResendResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "sent": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "enum": [
                  "whatsapp",
                  "email"
                ]
              },
              "result": {
                "type": "string",
                "enum": [
                  "sent",
                  "failed",
                  "skipped"
                ]
              },
              "detail": {
                "type": "string"
              }
            }
          },
          "description": "What happened per channel."
        },
        "note": {
          "type": "string",
          "description": "What happened, in one sentence."
        }
      }
    },
    "WebhookTestUrlRequest": {
      "type": "object",
      "required": [
        "url"
      ],
      "description": "One test POST to any https URL. Leave out data and raw for the sample of type.",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "example": "https://hooks.example.com/app2email",
          "description": "https only. A private address answers result.stage blocked_address."
        },
        "type": {
          "type": "string",
          "default": "ping",
          "example": "message.received",
          "description": "ping or a number event type (x-a2e-webhook-events, not the Partner group)."
        },
        "data": {
          "type": "object",
          "additionalProperties": true,
          "description": "Your own event data, sent in the normal envelope (at most 16 KB in all)."
        },
        "raw": {
          "type": "object",
          "additionalProperties": true,
          "description": "Sent as the whole body instead of an envelope."
        },
        "secret": {
          "type": "string",
          "maxLength": 200,
          "description": "Signs the test. Leave out for a new random one (answered in sent.secret)."
        },
        "format": {
          "type": "string",
          "enum": [
            "app2email",
            "meta"
          ],
          "default": "app2email",
          "description": "meta: the events that come from WhatsApp as Meta's own webhook body."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Up to 5 custom headers, the same rules as a webhook's."
        }
      }
    },
    "WebhookTestUrlResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "sent": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string"
            },
            "url": {
              "type": "string"
            },
            "headers": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "Every header sent, both signatures included."
            },
            "body": {
              "type": "string",
              "description": "The body exactly as sent and signed."
            },
            "secret": {
              "type": "string"
            },
            "secret_generated": {
              "type": "boolean",
              "description": "true: no secret was given, this one is new."
            }
          }
        },
        "result": {
          "type": "object",
          "properties": {
            "ok": {
              "type": "boolean",
              "description": "Your URL answered 2xx within 10 seconds."
            },
            "stage": {
              "type": "string",
              "enum": [
                "response",
                "dns",
                "connect",
                "tls",
                "timeout",
                "blocked_address"
              ],
              "description": "response: your URL answered (see status). Otherwise where it failed."
            },
            "status": {
              "type": "integer"
            },
            "ms": {
              "type": "integer"
            },
            "headers": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "A few of the answer's headers (Content-Type, Date, Server, Location, Retry-After ...)."
            },
            "body": {
              "type": "string",
              "description": "The first 1000 characters of the answer."
            },
            "body_truncated": {
              "type": "boolean"
            },
            "message": {
              "type": "string",
              "description": "What went wrong, in plain words."
            }
          }
        }
      }
    },
    "WebhookCatcher": {
      "type": "object",
      "properties": {
        "token": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "POST anything here: https://api.app2email.com/hooks/catch/<token>."
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "expires": {
          "type": "string",
          "format": "date-time"
        },
        "requests": {
          "type": "integer",
          "description": "How many it has received."
        },
        "full": {
          "type": "boolean",
          "description": "It has 50 requests: the next ones get 429."
        }
      }
    },
    "WebhookCatcherCreated": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "expires": {
          "type": "string",
          "format": "date-time"
        },
        "limits": {
          "type": "object",
          "properties": {
            "requests": {
              "type": "integer"
            },
            "body_max_bytes": {
              "type": "integer"
            },
            "minutes": {
              "type": "integer"
            }
          }
        },
        "note": {
          "type": "string"
        }
      }
    },
    "WebhookCatchersResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "catchers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/WebhookCatcher"
          }
        },
        "limits": {
          "type": "object",
          "properties": {
            "catchers": {
              "type": "integer"
            },
            "requests": {
              "type": "integer"
            },
            "body_max_bytes": {
              "type": "integer"
            }
          }
        }
      }
    },
    "WebhookCaughtRequest": {
      "type": "object",
      "properties": {
        "seq": {
          "type": "integer",
          "description": "1, 2, 3 ... in the order received."
        },
        "received": {
          "type": "string",
          "format": "date-time"
        },
        "method": {
          "type": "string"
        },
        "ip": {
          "type": "string",
          "description": "The sender's address; empty for app2email's own deliveries."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "body": {
          "type": "string",
          "description": "The body as text."
        },
        "body_truncated": {
          "type": "boolean",
          "description": "true: app2email's own delivery was larger than 64 KB and is kept cut."
        }
      }
    },
    "WebhookCatcherResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "created": {
          "type": "string",
          "format": "date-time"
        },
        "expires": {
          "type": "string",
          "format": "date-time"
        },
        "full": {
          "type": "boolean"
        },
        "count": {
          "type": "integer"
        },
        "requests": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/WebhookCaughtRequest"
          },
          "description": "Oldest first; with after, only the later ones."
        }
      }
    },
    "WebhookCatcherDeleteResponse": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "request_id": {
          "type": "string"
        },
        "deleted": {
          "type": "string"
        }
      }
    },
    "NumberWebhookTestRequest": {
      "type": "object",
      "description": "Optional. No body: a ping. type: that event's sample (GET .../webhooks/samples). event: the event you give, as it is (a missing id, created or number is filled in).",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "ping",
            "message.status",
            "message.received",
            "message.failed",
            "contact.opted_out",
            "broadcast.completed",
            "usage.threshold",
            "template.status_changed",
            "conversation.owner_changed",
            "message.held_for_approval",
            "approval.resolved",
            "contact.updated",
            "waitlist.joined",
            "waitlist.notified",
            "waitlist.removed",
            "booking.created",
            "booking.cancelled",
            "booking.rescheduled",
            "booking.rated",
            "flow.completed",
            "booking.updated",
            "booking.note.created",
            "calendar.block.created",
            "calendar.block.deleted",
            "call.incoming",
            "call.status",
            "message.edited",
            "message.deleted",
            "contact.changed_number",
            "number.updated",
            "number.error",
            "flow.status_changed",
            "booking.paid",
            "booking.refunded",
            "payment.paid",
            "package.purchased",
            "poll.voted",
            "poll.closed",
            "booking.customer.erased",
            "order.created",
            "order.paid",
            "order.accepted",
            "order.ready",
            "order.completed",
            "order.cancelled",
            "order.refunded",
            "order.no_show",
            "submission.created",
            "submission.files_ready",
            "submission.updated",
            "submission.status_changed",
            "submission.assigned",
            "submission.note_added",
            "submission.customer_replied",
            "submission.deleted",
            "submit.automation_failed",
            "ticket.order.confirmed",
            "ticket.order.refunded",
            "ticket.checked_in",
            "ticket.passed_on",
            "ticket.event.sold_out",
            "ticket.event.cancelled",
            "ticket.waitlist.joined",
            "ticket.buyer.erased"
          ],
          "example": "message.received"
        },
        "event": {
          "$ref": "#/definitions/WebhookEvent"
        }
      }
    }
  }
}
