# Change an automation, or switch it on or off

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

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

Scope: `submissions:manage`. Not with a sandbox key. Send the whole document (with `trigger` and `actions`) to replace it, or a body with neither of those to change only the keys it has: `{"enabled": false}` switches it off and keeps the rest. The result is checked as a whole (400 `invalid_automation`). Runs that are waiting (a `wait` action, a retry) continue with the new document.

|  |  |
| --- | --- |
| Scope | `submissions:manage` |
| Sandbox key | refused (https://www.app2email.com/docs/api/sandbox.md) |
| MCP tool | `update_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` |
| `id` | path | string | yes | The automation's id (GET /submit/automations).; eg `31` |

## Body

`application/json`, required

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string |  | 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 |  | 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[] |  | 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
{
  "enabled": false
}
```

## Responses

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | Saved. |  |
| 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` |

### 200

```json
{
  "success": true,
  "request_id": "a4upd",
  "automation": {
    "name": "Price a quote request in the ERP",
    "form": "quote",
    "enabled": false,
    "trigger": "submitted",
    "options": {},
    "conditions": {
      "all": [
        {
          "field": "quantity",
          "gt": 0
        }
      ]
    },
    "actions": [
      {
        "type": "http",
        "connection": "erp",
        "method": "POST",
        "path": "/quotes",
        "query": {},
        "headers": {
          "X-Source": "whatsapp"
        },
        "body": {
          "reference": "{reference}",
          "customer": {
            "name": "{contact.name}",
            "phone": "{contact.phone}"
          },
          "product": "{product}",
          "quantity": "{quantity}",
          "photos": "{files.photos}"
        },
        "save": {
          "erp_id": "$.id",
          "quote_amount": "$.total"
        },
        "on_fail": "retry"
      },
      {
        "type": "set_status",
        "status": "quoted",
        "note": "Priced by the ERP"
      },
      {
        "type": "reply",
        "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
        "buttons": [
          {
            "id": "accept",
            "title": "Accept",
            "set_status": "accepted"
          },
          {
            "id": "decline",
            "title": "Decline",
            "set_status": "declined"
          }
        ],
        "file": "",
        "link": true
      }
    ],
    "id": 31,
    "position": 0,
    "sentence": "When a Quote request is submitted, if quantity > 0: call ERP (POST /quotes), move to Quoted, reply with Accept / Decline",
    "runs": 18,
    "failures": 1,
    "last_run": "2026-11-13T04:00:00.000Z",
    "last_error": "",
    "created": "2026-11-12T22:30:00.000Z",
    "updated": "2026-11-12T22:30:00.000Z"
  }
}
```

## 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 PUT "https://api.app2email.com/v1/YOUR_NUMBER/submit/automations/31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'
```

## 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/{id}": {
      "put": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "updateAutomation",
        "summary": "Change an automation, or switch it on or off",
        "description": "Scope: `submissions:manage`. Not with a sandbox key. Send the whole document (with `trigger` and `actions`) to replace it, or a body with neither of those to change only the keys it has: `{\"enabled\": false}` switches it off and keeps the rest. The result is checked as a whole (400 `invalid_automation`). Runs that are waiting (a `wait` action, a retry) continue with the new document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Number"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The automation's id (GET /submit/automations).",
            "schema": {
              "type": "string",
              "example": "31"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitAutomationUpdateRequest"
              },
              "example": {
                "enabled": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitAutomationResponse"
                },
                "example": {
                  "success": true,
                  "request_id": "a4upd",
                  "automation": {
                    "name": "Price a quote request in the ERP",
                    "form": "quote",
                    "enabled": false,
                    "trigger": "submitted",
                    "options": {},
                    "conditions": {
                      "all": [
                        {
                          "field": "quantity",
                          "gt": 0
                        }
                      ]
                    },
                    "actions": [
                      {
                        "type": "http",
                        "connection": "erp",
                        "method": "POST",
                        "path": "/quotes",
                        "query": {},
                        "headers": {
                          "X-Source": "whatsapp"
                        },
                        "body": {
                          "reference": "{reference}",
                          "customer": {
                            "name": "{contact.name}",
                            "phone": "{contact.phone}"
                          },
                          "product": "{product}",
                          "quantity": "{quantity}",
                          "photos": "{files.photos}"
                        },
                        "save": {
                          "erp_id": "$.id",
                          "quote_amount": "$.total"
                        },
                        "on_fail": "retry"
                      },
                      {
                        "type": "set_status",
                        "status": "quoted",
                        "note": "Priced by the ERP"
                      },
                      {
                        "type": "reply",
                        "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                        "buttons": [
                          {
                            "id": "accept",
                            "title": "Accept",
                            "set_status": "accepted"
                          },
                          {
                            "id": "decline",
                            "title": "Decline",
                            "set_status": "declined"
                          }
                        ],
                        "file": "",
                        "link": true
                      }
                    ],
                    "id": 31,
                    "position": 0,
                    "sentence": "When a Quote request is submitted, if quantity > 0: call ERP (POST /quotes), move to Quoted, reply with Accept / Decline",
                    "runs": 18,
                    "failures": 1,
                    "last_run": "2026-11-13T04:00:00.000Z",
                    "last_error": "",
                    "created": "2026-11-12T22:30:00.000Z",
                    "updated": "2026-11-12T22:30:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "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": "update_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."
      },
      "SubmitAutomationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string"
          },
          "automation": {
            "$ref": "#/components/schemas/SubmitAutomation"
          }
        }
      },
      "SubmitAutomationUpdateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80,
            "example": "Large quotes go to a manager",
            "description": "What it is called in the list, up to 80 characters. POST /submit/setup replaces an automation with the same name on the same form."
          },
          "form": {
            "type": "string",
            "example": "quote",
            "description": "The key of the form it belongs to, or \"\" for every form."
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "description": "Its place in the list, lowest first."
          },
          "trigger": {
            "type": "string",
            "enum": [
              "submitted",
              "status_changed",
              "assigned",
              "updated",
              "note_added",
              "file_added",
              "customer_replied",
              "button",
              "overdue",
              "due",
              "manual"
            ],
            "description": "When it runs. `submitted`: A submission is complete: its files are stored (or 3 minutes passed without them, which is noted on the submission). `status_changed`: The stage changed. Options - to: Stage keys it moved to. [] = any. from: Stage keys it moved from. [] = any. `assigned`: The assignee changed. `updated`: Answers or internal fields were edited. Options - fields: Only when one of these field keys changed. [] = any. `note_added`: A member or the API wrote a note. `file_added`: A file was added after the submission was made. `customer_replied`: The submitter added text or files: after tapping Add more, with a follow-up form, or on their status page. `button`: The submitter pressed a button of a reply. Options - button: The button's id (a-z, 0-9 and _, up to 20 characters). \"\" = any button. `overdue`: The submission is still in the same stage after this long. Fires once per stay in a stage. Options - minutes: Needed: 5 to 43200 (30 days). stages: Only in these stage keys. [] = every open stage. `due`: The due time passed while the submission is open. Fires once per due time. `manual`: A member presses its button on the submission, or POST /submit/submissions/{id}/run names it. Options - label: The button's text, up to 30 characters. Left out: the automation's name."
          },
          "options": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "to": [
                "accepted"
              ],
              "from": []
            },
            "description": "The trigger's options (see trigger). {} when it has none."
          },
          "conditions": {
            "$ref": "#/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."
          }
        },
        "description": "Either the whole automation (with trigger and actions): it replaces what is stored. Or a part: a body with neither trigger nor actions changes only the keys it has (name, form, enabled, options, conditions, position). Either way the result is checked as a whole."
      },
      "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>"
      }
    }
  }
}
```

