# Create an automation: when, if, do

HTML: https://www.app2email.com/docs/api/submit-info/create-automation · Index: https://www.app2email.com/docs/api/llms.txt

`POST https://api.app2email.com/v1/{number}/submit/automations`

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.

|  |  |
| --- | --- |
| Scope | `submissions:manage` |
| Sandbox key | refused (https://www.app2email.com/docs/api/sandbox.md) |
| MCP tool | `create_automation` on https://api.app2email.com/mcp |

## Parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number` | path | string | yes | Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.; eg `4976659348270` |

## Body

`application/json`, required

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | yes | 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.; max 80 chars |
| `form` | string |  | The key of the form it belongs to, or "" for every form. |
| `enabled` | boolean |  |  |
| `position` | integer |  | Its place in the list, lowest first.; min 0 |
| `trigger` | string | yes | 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.; one of: `submitted`, `status_changed`, `assigned`, `updated`, `note_added`, `file_added`, `customer_replied`, `button`, `overdue`, `due`, `manual` |
| `options` | object |  | The trigger's options (see trigger). {} when it has none.; any keys |
| `conditions` | object |  | 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.; more keys allowed |
| `conditions.field` | string |  | 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. |
| `conditions.equals` | any |  |  |
| `conditions.not_equals` | any |  |  |
| `conditions.in` | any[] |  |  |
| `conditions.not_in` | any[] |  |  |
| `conditions.contains` | any |  |  |
| `conditions.empty` | boolean |  |  |
| `conditions.not_empty` | boolean |  |  |
| `conditions.gt` | any |  |  |
| `conditions.gte` | any |  |  |
| `conditions.lt` | any |  |  |
| `conditions.lte` | any |  |  |
| `conditions.all` | object[] |  | A group: every rule in it must hold. |
| `conditions.any` | object[] |  | A group: at least one rule in it must hold. |
| `actions` | object[] | yes | 1 to 20 actions, run in order.; 1–20 items |
| `actions.type` | string | yes | 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.; one of: `set_status`, `assign`, `set_field`, `calculate`, `tag`, `set_priority`, `set_due`, `reply`, `ask_location`, `send_form`, `email`, `notify`, `http`, `openapi`, `mcp`, `wait`, `stop` |
| `actions.status` | string |  | set_status. The stage key. |
| `actions.note` | string |  | set_status. The note of the change (needed when the stage has require_note). |
| `actions.to` | any |  | 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. |
| `actions.key` | string |  | 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. |
| `actions.value` | any |  | set_field. The value, with placeholders. |
| `actions.formula` | string |  | calculate. The formula (see the automation's description for the language).; max 500 chars |
| `actions.add` | string[] |  | tag. Tags to add. |
| `actions.remove` | string[] |  | tag. Tags to remove. |
| `actions.priority` | string |  | set_priority.; one of: `low`, `normal`, `high`, `urgent` |
| `actions.minutes` | integer |  | set_due: minutes from now, 0 to 525600 (0 takes the due time off). wait: how long to pause, 1 to 43200.; 0–525600 |
| `actions.text` | string |  | reply, ask_location, send_form, notify: the message, with placeholders. |
| `actions.buttons` | object[] |  | 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.; max 3 items |
| `actions.buttons.id` | string | yes |  |
| `actions.buttons.title` | string | yes | max 20 chars |
| `actions.buttons.set_status` | string |  | The stage the submission moves to when it is pressed. Left out: only the button trigger fires. |
| `actions.file` | string |  | reply. The key of a photo or document field whose files are sent along, or "". |
| `actions.link` | boolean |  | reply. true: add a button that opens the submitter's status page. |
| `actions.form` | string |  | send_form. The key of the form to send. |
| `actions.prefill` | object |  | send_form. Values for the new form: {"<field key>": value}, with placeholders. Up to 30 values.; any keys |
| `actions.subject` | string |  | email. |
| `actions.body` | any |  | 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. |
| `actions.attach_files` | boolean |  | email. true: attach the submission's files (up to 15 MB in all; above that their links are listed). Default false. |
| `actions.connection` | string |  | http, openapi, mcp. The connection's key (GET /submit/connections). http only: "" with a full url. |
| `actions.method` | string |  | http.; one of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
| `actions.path` | string |  | http. With a connection: added to its base address, for example /orders/{reference}. Each value a placeholder inserts is percent-encoded. |
| `actions.url` | string |  | http. Without a connection: the full https address. Placeholders may stand in the path and the query, not in the host name. |
| `actions.query` | object |  | http. Query parameters: {name: value}, up to 30.; any keys |
| `actions.headers` | object |  | 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-.; any keys |
| `actions.operation` | string |  | openapi. A function id of the connection (GET /submit/connections/{key}/functions). |
| `actions.params` | object |  | 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.; any keys |
| `actions.tool` | string |  | mcp. The tool's name (GET /submit/connections/{key}/functions). |
| `actions.arguments` | object |  | mcp. The tool's arguments: {name: value}, typed like a JSON body.; any keys |
| `actions.save` | object |  | 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).; any keys |
| `actions.on_fail` | string |  | 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).; one of: `retry`, `continue`, `stop` |

### Example

```json
{
  "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
    }
  ]
}
```

## Responses

| Status | Meaning | error.code |
| --- | --- | --- |
| 201 | Made. |  |
| 400 | The request is malformed (missing or invalid fields, query parameters or times). | `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` |
| 401 | Missing, invalid, revoked or expired API key. | `missing_api_key`, `invalid_authorization_header`, `invalid_api_key`, `api_key_old_format`, `api_key_revoked`, `api_key_expired` |
| 403 | The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. | `api_key_number_mismatch`, `insufficient_scope`, `ip_not_allowed`, `plan_not_allowed`, `service_not_live`, `recipient_opted_out`, `recipient_not_opted_in`, `template_name_reserved`, `whatsapp_payment_issue`, `whatsapp_account_locked`, `whatsapp_account_restricted`, `sandbox_key`, `recipient_stopped_marketing`, `messaging_limit_restricted`, `display_name_not_approved`, `username_not_eligible`, `account_not_confirmed`, `account_deactivated`, `booking_not_enabled`, `link_not_usable`, `call_permission_required`, `not_in_instant_sandbox`, `flow_blocked_by_integrity`, `whatsapp_permission_missing`, `partner_suspended`, `partner_closed`, `client_not_editable`, `shop_not_enabled`, `submit_not_enabled`, `tickets_not_enabled` |
| 404 | The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. | `number_not_found`, `template_not_found`, `template_language_not_found`, `message_not_found`, `broadcast_not_found`, `webhook_not_found`, `delivery_not_found`, `optin_not_found`, `request_not_found`, `conversation_not_found`, `contact_not_found`, `segment_not_found`, `approval_not_found`, `media_not_found`, `route_not_found`, `key_not_found`, `dataset_not_found`, `waitlist_not_found`, `booking_not_found`, `block_not_found`, `note_not_found`, `link_not_found`, `hold_not_found`, `flow_not_found`, `flow_json_not_found`, `qr_code_not_found`, `client_not_found`, `payment_not_found`, `package_not_found`, `poll_not_found`, `shop_not_found`, `form_not_found`, `submission_not_found`, `automation_not_found`, `connection_not_found`, `member_not_found`, `list_not_found`, `ticket_event_not_found`, `ticket_date_not_found`, `ticket_type_not_found`, `ticket_order_not_found`, `ticket_not_found`, `ticket_code_not_found`, `ticket_check_in_not_found`, `catcher_not_found` |
| 415 | The body is not JSON. | `unsupported_content_type` |
| 429 | A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. | `monthly_limit_reached`, `too_many_messages_to_recipient`, `whatsapp_rate_limit`, `rate_limited`, `daily_cap_reached`, `monthly_cap_reached`, `too_many_tests`, `register_limit_reached`, `too_many_signups`, `media_lookups_paused`, `too_many_invites` |
| 500 | Unexpected error on app2email's side. | `internal_error`, `background_start_failed`, `schedule_failed`, `shop_failed` |
| 503 | app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. | `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` |

### 201

```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"
  }
}
```

## Errors

[`api_key_expired`](https://www.app2email.com/docs/api/errors#api_key_expired), [`api_key_number_mismatch`](https://www.app2email.com/docs/api/errors#api_key_number_mismatch), [`api_key_old_format`](https://www.app2email.com/docs/api/errors#api_key_old_format), [`api_key_revoked`](https://www.app2email.com/docs/api/errors#api_key_revoked), [`automation_not_found`](https://www.app2email.com/docs/api/errors#automation_not_found), [`insufficient_scope`](https://www.app2email.com/docs/api/errors#insufficient_scope), [`internal_error`](https://www.app2email.com/docs/api/errors#internal_error), [`invalid_api_key`](https://www.app2email.com/docs/api/errors#invalid_api_key), [`invalid_authorization_header`](https://www.app2email.com/docs/api/errors#invalid_authorization_header), [`invalid_automation`](https://www.app2email.com/docs/api/errors#invalid_automation), [`invalid_json`](https://www.app2email.com/docs/api/errors#invalid_json), [`invalid_number_in_url`](https://www.app2email.com/docs/api/errors#invalid_number_in_url), [`ip_not_allowed`](https://www.app2email.com/docs/api/errors#ip_not_allowed), [`missing_api_key`](https://www.app2email.com/docs/api/errors#missing_api_key), [`number_not_found`](https://www.app2email.com/docs/api/errors#number_not_found), [`plan_not_allowed`](https://www.app2email.com/docs/api/errors#plan_not_allowed), [`rate_limited`](https://www.app2email.com/docs/api/errors#rate_limited), [`sandbox_key`](https://www.app2email.com/docs/api/errors#sandbox_key), [`service_not_live`](https://www.app2email.com/docs/api/errors#service_not_live), [`submit_not_ready`](https://www.app2email.com/docs/api/errors#submit_not_ready)

## Example

```bash
curl -X POST "https://api.app2email.com/v1/YOUR_NUMBER/submit/automations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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
    }
  ]
}'
```

## OpenAPI

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "app2email WhatsApp API",
    "version": "1.4.0"
  },
  "servers": [
    {
      "url": "https://api.app2email.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/{number}/submit/automations": {
      "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": [
          {
            "$ref": "#/components/parameters/Number"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitAutomationInput"
              },
              "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
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitAutomationResponse"
                },
                "example": {
                  "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "415": {
            "description": "The body is not JSON. Possible error.code values: unsupported_content_type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-a2e-webhook-events": [],
        "x-a2e-error-codes": [
          "api_key_expired",
          "api_key_number_mismatch",
          "api_key_old_format",
          "api_key_revoked",
          "automation_not_found",
          "insufficient_scope",
          "internal_error",
          "invalid_api_key",
          "invalid_authorization_header",
          "invalid_automation",
          "invalid_json",
          "invalid_number_in_url",
          "ip_not_allowed",
          "missing_api_key",
          "number_not_found",
          "plan_not_allowed",
          "rate_limited",
          "sandbox_key",
          "service_not_live",
          "submit_not_ready"
        ],
        "x-a2e-scope": "submissions:manage",
        "x-a2e-sandbox": "refused",
        "x-a2e-mcp-tool": "create_automation",
        "x-a2e-needs": null
      }
    }
  },
  "components": {
    "parameters": {
      "Number": {
        "name": "number",
        "in": "path",
        "required": true,
        "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]{8,15}$",
          "example": "4976659348270"
        }
      }
    },
    "schemas": {
      "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."
          }
        }
      },
      "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": "#/components/schemas/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": "#/components/schemas/Component"
                  }
                }
              }
            }
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": "#/components/schemas/SendTemplateRequest"
          },
          "whatsapp_error": {
            "$ref": "#/components/schemas/WhatsAppError"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "request_id": {
            "type": "string",
            "example": "kxrkf",
            "description": "Quote this when contacting support."
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "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."
          }
        }
      },
      "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."
          }
        }
      },
      "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"
                  }
                }
              ]
            }
          }
        }
      },
      "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'."
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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."
          }
        }
      },
      "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": "#/components/schemas/Media"
          },
          "video": {
            "$ref": "#/components/schemas/Media"
          },
          "document": {
            "$ref": "#/components/schemas/Media"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "date_time": {
            "$ref": "#/components/schemas/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)."
          }
        }
      },
      "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."
          }
        }
      },
      "Recipient": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "One number, with country code."
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/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)."
          }
        }
      },
      "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": "#/components/schemas/Interactive",
            "description": "type 'interactive': reply buttons, a list, or a URL button."
          },
          "template": {
            "$ref": "#/components/schemas/Template"
          },
          "text": {
            "$ref": "#/components/schemas/FreeFormText",
            "description": "type 'text': the message."
          },
          "image": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'image': link, data+filename or id, and an optional caption."
          },
          "video": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'video': link, data+filename or id, and an optional caption."
          },
          "document": {
            "$ref": "#/components/schemas/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": "#/components/schemas/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": "#/components/schemas/AudioContent",
            "description": "type 'audio'."
          },
          "sticker": {
            "$ref": "#/components/schemas/StickerContent",
            "description": "type 'sticker'."
          },
          "location": {
            "$ref": "#/components/schemas/LocationContent",
            "description": "type 'location'."
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactCard"
            },
            "description": "type 'contacts': 1 to 20 cards."
          },
          "reaction": {
            "$ref": "#/components/schemas/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."
          }
        }
      },
      "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"
          }
        }
      },
      "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."
      },
      "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": "#/components/schemas/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": "#/components/schemas/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."
      },
      "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": "#/components/schemas/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": "#/components/schemas/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\"]}]}."
      },
      "SubmitAutomationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string"
          },
          "automation": {
            "$ref": "#/components/schemas/SubmitAutomation"
          }
        }
      },
      "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"
              ]
            }
          ]
        }
      },
      "Template": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "order_update",
            "description": "Exact name of an APPROVED template."
          },
          "language": {
            "$ref": "#/components/schemas/Language"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            },
            "description": "Values for the template's placeholders and media. Leave out for templates without parameters."
          }
        }
      },
      "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"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer <your API key>"
      }
    }
  }
}
```

