# Send a WhatsApp message: template, or free-form reply

HTML: https://www.app2email.com/docs/api/messages/send-template-message · Index: https://www.app2email.com/docs/api/llms.txt

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

Sends one approved template to one recipient, or to several when `to` lists several numbers (or `recipients` gives each number its own values). The parameters are checked against the template before sending; on a mismatch the error includes a complete, correct `example_request` for that template. Nothing is sent when the request itself is invalid. `dry_run` checks without sending; `background` answers 202 and sends after; `send_at` schedules it (202, status scheduled). `type` text, image, video, document or interactive sends a free-form message to one contact within 24 hours of the contact's last message (422 outside_24h_window otherwise). `segment` sends a template to a saved segment's contacts. A business-scoped user id works wherever a number does. Also `audio`, `sticker`, `location`, `contacts`, `reaction` and the newer interactive kinds; template carousels, limited-time offers, catalog, MPM, SPM, flow and OTP buttons. `callback_data` comes back in message.status. MARKETING templates follow `marketing_api` / messages.marketing_route (`sent_via` in the answer).

|  |  |
| --- | --- |
| Scope | `messages:send` |
| Sandbox key | simulated (https://www.app2email.com/docs/api/sandbox.md) |
| Idempotency-Key | accepted (safe retries, 24 h) |
| MCP tool | `send_template` 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` |
| `Idempotency-Key` | header | string |  | Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.; eg `order-1234-shipped` |

## Body

`application/json`, required

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `messaging_product` | string |  | Optional. Always 'whatsapp'.; one of: `whatsapp` |
| `recipient_type` | string |  | Optional. Always 'individual'.; one of: `individual` |
| `to` | string |  | 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` | string |  | Optional, instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'. |
| `segment` | string |  | 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` | string |  | '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.; one of: `template`, `text`, `image`, `video`, `document`, `interactive`, `audio`, `sticker`, `location`, `contacts`, `reaction` |
| `interactive` | object |  | type 'interactive': reply buttons, a list, or a URL button. |
| `interactive.type` | string | yes | one of: `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` |
| `interactive.header` | object |  | any keys |
| `interactive.body` | object |  |  |
| `interactive.body.text` | string | yes | max 1024 chars |
| `interactive.footer` | object |  |  |
| `interactive.footer.text` | string |  | max 60 chars |
| `interactive.action` | object | yes | any keys |
| `template` | object |  |  |
| `template.name` | string | yes | Exact name of an APPROVED template. |
| `template.language` | object |  | Required when the template exists in more than one language. |
| `template.language.code` | string | yes | Template language code, eg 'en', 'en_US', 'nl'. |
| `template.components` | object[] |  | Values for the template's placeholders and media. Leave out for templates without parameters. |
| `template.components.type` | string | yes | one of: `header`, `body`, `button`, `carousel`, `limited_time_offer` |
| `template.components.sub_type` | string |  | Buttons only.; one of: `url`, `quick_reply`, `copy_code`, `flow`, `catalog`, `mpm`, `spm`, `order_details` |
| `template.components.index` | string |  | Buttons only: position of the button in the template, starting at 0. |
| `template.components.parameters` | object[] |  |  |
| `template.components.parameters.type` | string | yes | one of: `text`, `image`, `video`, `document`, `location`, `currency`, `date_time`, `payload`, `coupon_code`, `action`, `product`, `limited_time_offer` |
| `template.components.parameters.parameter_name` | string |  | For templates with NAMED placeholders, eg 'first_name' for {{first_name}}. |
| `template.components.parameters.text` | string |  | type 'text'. No new lines, tabs or more than 4 spaces in a row. |
| `template.components.parameters.image` | object |  | Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out. |
| `template.components.parameters.image.link` | string |  | Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp. |
| `template.components.parameters.image.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `template.components.parameters.image.id` | string |  | A media id already uploaded to WhatsApp for this number. |
| `template.components.parameters.image.filename` | string |  | Shown to the recipient for documents. Also helps detect the file type. |
| `template.components.parameters.image.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `template.components.parameters.video` | object |  | Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out. |
| `template.components.parameters.video.link` | string |  | Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp. |
| `template.components.parameters.video.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `template.components.parameters.video.id` | string |  | A media id already uploaded to WhatsApp for this number. |
| `template.components.parameters.video.filename` | string |  | Shown to the recipient for documents. Also helps detect the file type. |
| `template.components.parameters.video.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `template.components.parameters.document` | object |  | Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out. |
| `template.components.parameters.document.link` | string |  | Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp. |
| `template.components.parameters.document.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `template.components.parameters.document.id` | string |  | A media id already uploaded to WhatsApp for this number. |
| `template.components.parameters.document.filename` | string |  | Shown to the recipient for documents. Also helps detect the file type. |
| `template.components.parameters.document.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `template.components.parameters.location` | object |  |  |
| `template.components.parameters.location.latitude` | string | yes |  |
| `template.components.parameters.location.longitude` | string | yes |  |
| `template.components.parameters.location.name` | string |  |  |
| `template.components.parameters.location.address` | string |  |  |
| `template.components.parameters.currency` | object |  |  |
| `template.components.parameters.currency.fallback_value` | string |  |  |
| `template.components.parameters.currency.code` | string |  |  |
| `template.components.parameters.currency.amount_1000` | integer |  |  |
| `template.components.parameters.date_time` | object |  |  |
| `template.components.parameters.date_time.fallback_value` | string |  |  |
| `template.components.parameters.payload` | string |  | type 'payload': quick reply button payload. |
| `template.components.parameters.coupon_code` | string |  | type 'coupon_code': copy code button value. |
| `template.components.parameters.action` | object |  | type 'action': flow / catalog button data, as WhatsApp Cloud API.; any keys |
| `template.components.parameters.product` | object |  | type 'product': a product header. |
| `template.components.parameters.product.product_retailer_id` | string |  |  |
| `template.components.parameters.product.catalog_id` | string |  |  |
| `template.components.parameters.limited_time_offer` | object |  | type 'limited_time_offer': when the offer ends (ms since 1970). |
| `template.components.parameters.limited_time_offer.expiration_time_ms` | integer |  |  |
| `template.components.cards` | object[] |  | type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}. |
| `template.components.cards.card_index` | integer |  |  |
| `template.components.cards.components` | object[] |  |  |
| `text` | object |  | type 'text': the message. |
| `text.body` | string | yes | The text. Up to 4096 characters. |
| `text.preview_url` | boolean |  | true: show a preview of a link in the text. |
| `image` | object |  | type 'image': link, data+filename or id, and an optional caption. |
| `image.link` | string |  | Public http(s) URL. app2email downloads the file and uploads it to WhatsApp. |
| `image.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `image.id` | string |  | A media id from POST /media (or uploaded to WhatsApp for this number). |
| `image.filename` | string |  | Needed with 'data' for documents. |
| `image.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `image.caption` | string |  | Optional text under the image, video or document.; max 1024 chars |
| `video` | object |  | type 'video': link, data+filename or id, and an optional caption. |
| `video.link` | string |  | Public http(s) URL. app2email downloads the file and uploads it to WhatsApp. |
| `video.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `video.id` | string |  | A media id from POST /media (or uploaded to WhatsApp for this number). |
| `video.filename` | string |  | Needed with 'data' for documents. |
| `video.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `video.caption` | string |  | Optional text under the image, video or document.; max 1024 chars |
| `document` | object |  | type 'document': link, data+filename or id, and an optional caption. |
| `document.link` | string |  | Public http(s) URL. app2email downloads the file and uploads it to WhatsApp. |
| `document.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `document.id` | string |  | A media id from POST /media (or uploaded to WhatsApp for this number). |
| `document.filename` | string |  | Needed with 'data' for documents. |
| `document.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `document.caption` | string |  | Optional text under the image, video or document.; max 1024 chars |
| `reply_to` | string |  | 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` | string |  | 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` | string |  | 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.; max 100 chars |
| `recipients` | object[] |  | 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. |
| `recipients.to` | string | yes | One number, with country code. |
| `recipients.components` | object[] |  | Only what differs for this number, eg its body values. The rest comes from template.components. |
| `recipients.components.type` | string | yes | one of: `header`, `body`, `button`, `carousel`, `limited_time_offer` |
| `recipients.components.sub_type` | string |  | Buttons only.; one of: `url`, `quick_reply`, `copy_code`, `flow`, `catalog`, `mpm`, `spm`, `order_details` |
| `recipients.components.index` | string |  | Buttons only: position of the button in the template, starting at 0. |
| `recipients.components.parameters` | object[] |  |  |
| `recipients.components.parameters.type` | string | yes | one of: `text`, `image`, `video`, `document`, `location`, `currency`, `date_time`, `payload`, `coupon_code`, `action`, `product`, `limited_time_offer` |
| `recipients.components.parameters.parameter_name` | string |  | For templates with NAMED placeholders, eg 'first_name' for {{first_name}}. |
| `recipients.components.parameters.text` | string |  | type 'text'. No new lines, tabs or more than 4 spaces in a row. |
| `recipients.components.parameters.image` | object |  | Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out. |
| `recipients.components.parameters.image.link` | string |  | Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp. |
| `recipients.components.parameters.image.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `recipients.components.parameters.image.id` | string |  | A media id already uploaded to WhatsApp for this number. |
| `recipients.components.parameters.image.filename` | string |  | Shown to the recipient for documents. Also helps detect the file type. |
| `recipients.components.parameters.image.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `recipients.components.parameters.video` | object |  | Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out. |
| `recipients.components.parameters.video.link` | string |  | Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp. |
| `recipients.components.parameters.video.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `recipients.components.parameters.video.id` | string |  | A media id already uploaded to WhatsApp for this number. |
| `recipients.components.parameters.video.filename` | string |  | Shown to the recipient for documents. Also helps detect the file type. |
| `recipients.components.parameters.video.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `recipients.components.parameters.document` | object |  | Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out. |
| `recipients.components.parameters.document.link` | string |  | Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp. |
| `recipients.components.parameters.document.data` | string |  | The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted. |
| `recipients.components.parameters.document.id` | string |  | A media id already uploaded to WhatsApp for this number. |
| `recipients.components.parameters.document.filename` | string |  | Shown to the recipient for documents. Also helps detect the file type. |
| `recipients.components.parameters.document.mime_type` | string |  | Optional. The type is detected from the file where possible. |
| `recipients.components.parameters.location` | object |  |  |
| `recipients.components.parameters.location.latitude` | string | yes |  |
| `recipients.components.parameters.location.longitude` | string | yes |  |
| `recipients.components.parameters.location.name` | string |  |  |
| `recipients.components.parameters.location.address` | string |  |  |
| `recipients.components.parameters.currency` | object |  |  |
| `recipients.components.parameters.currency.fallback_value` | string |  |  |
| `recipients.components.parameters.currency.code` | string |  |  |
| `recipients.components.parameters.currency.amount_1000` | integer |  |  |
| `recipients.components.parameters.date_time` | object |  |  |
| `recipients.components.parameters.date_time.fallback_value` | string |  |  |
| `recipients.components.parameters.payload` | string |  | type 'payload': quick reply button payload. |
| `recipients.components.parameters.coupon_code` | string |  | type 'coupon_code': copy code button value. |
| `recipients.components.parameters.action` | object |  | type 'action': flow / catalog button data, as WhatsApp Cloud API.; any keys |
| `recipients.components.parameters.product` | object |  | type 'product': a product header. |
| `recipients.components.parameters.product.product_retailer_id` | string |  |  |
| `recipients.components.parameters.product.catalog_id` | string |  |  |
| `recipients.components.parameters.limited_time_offer` | object |  | type 'limited_time_offer': when the offer ends (ms since 1970). |
| `recipients.components.parameters.limited_time_offer.expiration_time_ms` | integer |  |  |
| `recipients.components.cards` | object[] |  | type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}. |
| `recipients.components.cards.card_index` | integer |  |  |
| `recipients.components.cards.components` | object[] |  |  |
| `recipients.recipient_identity_key_hash` | string |  | Optional: this contact's identity_key_hash (see the request's).; max 200 chars |
| `dry_run` | boolean |  | Optional, app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything. |
| `background` | boolean |  | 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` | object |  | type 'audio'. |
| `audio.link` | string |  | Public http(s) URL. app2email downloads the file and uploads it to WhatsApp. |
| `audio.data` | string |  | The file, base64 encoded. |
| `audio.id` | string |  | A media id from POST /media. |

### Example: Body with two text values

```json
{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "#1234"
          }
        ]
      }
    ]
  }
}
```

### Example: Image header from a link, plus a URL button value

```json
{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "new_arrivals",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/photo.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "summer-sale"
          }
        ]
      }
    ]
  }
}
```

### Example: PDF header sent as base64 in the request

```json
{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "invoice_ready",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "document",
            "document": {
              "data": "JVBERi0xLjQKJ...",
              "filename": "invoice-1234.pdf"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "#1234"
          }
        ]
      }
    ]
  }
}
```

### Example: Template with named placeholders

```json
{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "welcome",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "parameter_name": "first_name",
            "text": "John"
          },
          {
            "type": "text",
            "parameter_name": "code",
            "text": "X7Q2"
          }
        ]
      }
    ]
  }
}
```

### Example: Same message to several numbers

```json
{
  "to": "61412345678,61498765432,61400111222",
  "type": "template",
  "campaign_name": "Order updates 21 Oct",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "#1234"
          }
        ]
      }
    ]
  }
}
```

### Example: Each number with its own values (recipients)

```json
{
  "type": "template",
  "campaign_name": "Order updates",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/photo.jpg"
            }
          }
        ]
      }
    ]
  },
  "recipients": [
    {
      "to": "61412345678",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "John"
            },
            {
              "type": "text",
              "text": "#1234"
            }
          ]
        }
      ]
    },
    {
      "to": "61498765432",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Mary"
            },
            {
              "type": "text",
              "text": "#1235"
            }
          ]
        }
      ]
    }
  ]
}
```

### Example: Check everything without sending

```json
{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "#1234"
          }
        ]
      }
    ]
  },
  "dry_run": true
}
```

### Example: Big list: answer now, send after

```json
{
  "to": "61412345678,61498765432,61400111222",
  "type": "template",
  "campaign_name": "October newsletter",
  "background": true,
  "template": {
    "name": "october_newsletter",
    "language": {
      "code": "en"
    }
  }
}
```

### Example: Free-form text reply (within 24 hours)

```json
{
  "to": "61412345678",
  "type": "text",
  "text": {
    "body": "Thanks, it arrives on Friday.",
    "preview_url": false
  }
}
```

### Example: Free-form image from a link, with a caption

```json
{
  "to": "61412345678",
  "type": "image",
  "image": {
    "link": "https://example.com/photo.jpg",
    "caption": "Your parcel"
  }
}
```

### Example: Free-form PDF as base64, quoting a message

```json
{
  "to": "61412345678",
  "type": "document",
  "reply_to": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
  "document": {
    "data": "JVBERi0xLjQKJ...",
    "filename": "invoice-1234.pdf",
    "caption": "Invoice #1234"
  }
}
```

### Example: Several numbers, sent at a set time

```json
{
  "to": "61412345678,61498765432,61400111222",
  "type": "template",
  "campaign_name": "Order updates 2 Nov",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "#1234"
          }
        ]
      }
    ]
  },
  "send_at": "2026-11-02T09:00:00+11:00"
}
```

### Example: Reply buttons (within 24 hours)

```json
{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Confirm your booking for Friday 10:00?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "yes",
            "title": "Confirm"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "no",
            "title": "Change"
          }
        }
      ]
    }
  }
}
```

### Example: A list to pick from (within 24 hours)

```json
{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": {
      "text": "Which time suits you?"
    },
    "action": {
      "button": "Pick a time",
      "sections": [
        {
          "title": "Friday",
          "rows": [
            {
              "id": "fri10",
              "title": "10:00"
            },
            {
              "id": "fri14",
              "title": "14:00",
              "description": "afternoon"
            }
          ]
        }
      ]
    }
  }
}
```

### Example: A contact known by a business-scoped user id

```json
{
  "recipient": "61.AbC123xyz",
  "type": "text",
  "text": {
    "body": "Thanks, it arrives on Friday."
  }
}
```

### Example: A template to a saved segment, values from each contact

```json
{
  "segment": "VIP, consented",
  "type": "template",
  "campaign_name": "November offer",
  "template": {
    "name": "november_offer",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "parameter_name": "first_name"
          }
        ]
      }
    ]
  }
}
```

### Example: Text

```json
{
  "to": "61412345678",
  "type": "text",
  "text": {
    "body": "Your order has shipped.",
    "preview_url": false
  }
}
```

### Example: Image

```json
{
  "to": "61412345678",
  "type": "image",
  "image": {
    "link": "https://example.com/photo.jpg",
    "caption": "Your parcel"
  }
}
```

### Example: Video

```json
{
  "to": "61412345678",
  "type": "video",
  "video": {
    "link": "https://example.com/howto.mp4",
    "caption": "How to set it up"
  }
}
```

### Example: Document

```json
{
  "to": "61412345678",
  "type": "document",
  "document": {
    "link": "https://example.com/invoice-1234.pdf",
    "filename": "invoice-1234.pdf",
    "caption": "Invoice"
  }
}
```

## Responses

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | Accepted by WhatsApp (all numbers, when several were given). A dry run also answers 200. A free-form message answers 200 too. A sandbox key answers 200 with sandbox: true. |  |
| 202 | "background": true - checked, and sending has started (progress: broadcast.status_url). Or "send_at" - status scheduled, sent at scheduled_for (cancel with POST /broadcasts/{code}/cancel). Or status pending_approval: held by the key's approval gate until a person approves it (approval.url). The example is the background answer. |  |
| 207 | Several numbers: some were accepted, some not. 'results' has the outcome per number. |  |
| 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` |
| 409 | Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. | `idempotency_request_in_progress`, `idempotency_request_interrupted`, `template_already_exists`, `broadcast_not_cancellable`, `broadcast_cancelled`, `webhook_url_in_use`, `approval_already_resolved`, `approval_expired`, `segment_exists`, `number_already_verified`, `username_taken`, `number_not_live`, `key_limit_reached`, `key_limits_unavailable`, `plan_not_available`, `plan_already_active`, `waitlist_not_set_up`, `waitlist_not_offered`, `booking_slot_taken`, `booking_cancelled`, `hold_expired`, `slug_taken`, `flow_not_editable`, `flow_not_published`, `flow_not_deletable`, `flow_name_taken`, `encryption_key_managed`, `username_not_available`, `client_exists`, `payments_not_connected`, `refund_not_possible`, `too_late`, `shop_not_tracked`, `shop_sku_taken`, `shop_limit`, `shop_changed`, `shop_order_problems`, `form_not_published`, `form_has_submissions`, `form_exists`, `connection_in_use`, `stage_not_allowed`, `template_not_editable`, `template_category_locked`, `template_insights_not_enabled`, `tickets_not_on_sale`, `tickets_sold_out`, `ticket_seat_not_available`, `ticket_limit_reached`, `ticket_not_allowed`, `ticket_event_not_publishable`, `delivery_in_progress` |
| 413 | The request or the media file is too large. | `request_too_large`, `media_too_large`, `approval_body_too_large`, `test_event_too_large`, `flow_json_too_large` |
| 415 | The body is not JSON. | `unsupported_content_type` |
| 422 | The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). | `template_not_approved`, `template_parameters_invalid`, `invalid_base64`, `invalid_media_link`, `media_download_failed`, `media_type_not_allowed`, `recipient_not_allowed`, `recipient_unreachable`, `template_parameter_count_mismatch`, `template_text_too_long`, `template_format_policy`, `template_parameter_format_mismatch`, `template_paused`, `template_disabled`, `template_parameter_invalid`, `required_parameter_missing`, `parameter_value_invalid`, `media_download_error`, `media_upload_error`, `idempotency_key_reused`, `invalid_webhook_url`, `outside_24h_window`, `text_too_long`, `caption_too_long`, `invalid_email`, `template_rejected`, `bsuid_not_supported`, `marketing_per_user_limit`, `recipient_in_experiment`, `template_not_marketing`, `recipient_is_sender`, `whatsapp_parameter_error`, `block_users_failed`, `block_list_full`, `username_change_limit`, `sandbox_recipient`, `flow_cannot_publish`, `flow_rejected`, `reaction_too_old`, `message_too_old`, `voice_needs_ogg_opus`, `marketing_disabled_on_cloud_api`, `recipient_identity_changed`, `username_account_not_linked`, `template_limit_reached`, `template_insights_unavailable`, `template_archive_failed`, `template_unarchive_failed`, `template_compare_unavailable` |
| 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` |
| 502 | WhatsApp (Meta) returned an error or could not be reached. | `template_lookup_failed`, `media_upload_failed`, `template_sample_media_failed`, `template_delete_failed`, `whatsapp_error`, `block_users_error`, `account_service_error`, `payment_link_failed`, `email_not_sent`, `flow_json_download_failed`, `media_lookup_failed`, `media_delete_failed`, `marketing_status_lookup_failed`, `contact_book_error`, `profile_photo_failed`, `payment_provider_error`, `shop_payment_failed`, `whatsapp_flow_failed`, `connection_failed` |
| 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": "kxrkf",
  "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
  "status": "accepted",
  "from": "4976659348270",
  "to": "61412345678",
  "template": {
    "name": "order_update",
    "language": "en",
    "category": "UTILITY"
  },
  "text": "Hi John, your order #1234 has shipped.",
  "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_...",
  "note": "accepted by WhatsApp. delivery and read status appear in your app2email Activity Log (WhatsApp sent).",
  "contacts": [
    {
      "input": "61412345678",
      "wa_id": "61412345678"
    }
  ]
}
```

### 202

```json
{
  "success": true,
  "request_id": "t7wpe",
  "status": "queued",
  "from": "4976659348270",
  "template": {
    "name": "october_newsletter",
    "language": "en",
    "category": "MARKETING"
  },
  "broadcast": {
    "name": "October newsletter",
    "code": "k3XbQ9rTzP2mWv7a1c9e",
    "report_url": "https://www.app2email.com/dashboard/log/broadcast/k3XbQ9rTzP2mWv7a1c9e",
    "status_url": "https://api.app2email.com/v1/4976659348270/broadcasts/k3XbQ9rTzP2mWv7a1c9e"
  },
  "recipients": 3,
  "queued": 3,
  "skipped": 0,
  "results": [],
  "note": "Sending in the background. GET broadcast.status_url for progress and the result for each number, or use the broadcast.completed webhook."
}
```

### 207

```json
{
  "success": false,
  "request_id": "q8m2d",
  "status": "partially_accepted",
  "from": "4976659348270",
  "template": {
    "name": "order_update",
    "language": "en",
    "category": "UTILITY"
  },
  "text": "Hi John, your order #1234 has shipped.",
  "broadcast": {
    "name": "Order updates 21 Oct",
    "code": "k3XbQ9rTzP2mWv7a1c9e",
    "report_url": "https://www.app2email.com/dashboard/log/broadcast/k3XbQ9rTzP2mWv7a1c9e"
  },
  "recipients": 3,
  "accepted": 2,
  "failed": 1,
  "results": [
    {
      "to": "61412345678",
      "success": true,
      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
      "status": "accepted",
      "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
    },
    {
      "to": "61498765432",
      "success": true,
      "message_id": "wamid.HBgLNjE0OTg3NjU0MzIVAgARGBJTQU1QTEVfT1VUQk9VTkQwMgA=",
      "status": "accepted",
      "conversation_url": "https://www.app2email.com/conversation/61498765432_4976659348270_..."
    },
    {
      "to": "61400111222",
      "success": false,
      "error": {
        "code": "recipient_unreachable",
        "message": "WhatsApp did not send the message: ...",
        "how_to_fix": "WhatsApp could not deliver to this number. Check it is a WhatsApp number written with its country code ..."
      }
    }
  ],
  "note": "accepted by WhatsApp. delivery and read status appear in your app2email Activity Log under Broadcasts (broadcast.report_url)."
}
```

## 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), [`approval_body_too_large`](https://www.app2email.com/docs/api/errors#approval_body_too_large), [`background_start_failed`](https://www.app2email.com/docs/api/errors#background_start_failed), [`block_list_busy`](https://www.app2email.com/docs/api/errors#block_list_busy), [`block_list_full`](https://www.app2email.com/docs/api/errors#block_list_full), [`block_users_error`](https://www.app2email.com/docs/api/errors#block_users_error), [`block_users_failed`](https://www.app2email.com/docs/api/errors#block_users_failed), [`broadcast_cancelled`](https://www.app2email.com/docs/api/errors#broadcast_cancelled), [`bsuid_not_supported`](https://www.app2email.com/docs/api/errors#bsuid_not_supported), [`call_permission_required`](https://www.app2email.com/docs/api/errors#call_permission_required), [`caption_not_supported`](https://www.app2email.com/docs/api/errors#caption_not_supported), [`caption_too_long`](https://www.app2email.com/docs/api/errors#caption_too_long), [`daily_cap_reached`](https://www.app2email.com/docs/api/errors#daily_cap_reached), [`display_name_not_approved`](https://www.app2email.com/docs/api/errors#display_name_not_approved), [`duplicate_recipients`](https://www.app2email.com/docs/api/errors#duplicate_recipients), [`free_form_single_recipient`](https://www.app2email.com/docs/api/errors#free_form_single_recipient), [`idempotency_key_reused`](https://www.app2email.com/docs/api/errors#idempotency_key_reused), [`idempotency_request_in_progress`](https://www.app2email.com/docs/api/errors#idempotency_request_in_progress), [`idempotency_request_interrupted`](https://www.app2email.com/docs/api/errors#idempotency_request_interrupted), [`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_base64`](https://www.app2email.com/docs/api/errors#invalid_base64), [`invalid_callback_data`](https://www.app2email.com/docs/api/errors#invalid_callback_data), [`invalid_components`](https://www.app2email.com/docs/api/errors#invalid_components), [`invalid_contacts_message`](https://www.app2email.com/docs/api/errors#invalid_contacts_message), [`invalid_cursor`](https://www.app2email.com/docs/api/errors#invalid_cursor), [`invalid_idempotency_key`](https://www.app2email.com/docs/api/errors#invalid_idempotency_key), [`invalid_identity_key_hash`](https://www.app2email.com/docs/api/errors#invalid_identity_key_hash), [`invalid_interactive`](https://www.app2email.com/docs/api/errors#invalid_interactive), [`invalid_json`](https://www.app2email.com/docs/api/errors#invalid_json), [`invalid_location`](https://www.app2email.com/docs/api/errors#invalid_location), [`invalid_marketing_api`](https://www.app2email.com/docs/api/errors#invalid_marketing_api), [`invalid_media_link`](https://www.app2email.com/docs/api/errors#invalid_media_link), [`invalid_number_in_url`](https://www.app2email.com/docs/api/errors#invalid_number_in_url), [`invalid_reaction`](https://www.app2email.com/docs/api/errors#invalid_reaction), [`invalid_recipients`](https://www.app2email.com/docs/api/errors#invalid_recipients), [`invalid_reply_to`](https://www.app2email.com/docs/api/errors#invalid_reply_to), [`invalid_send_at`](https://www.app2email.com/docs/api/errors#invalid_send_at), [`invalid_to`](https://www.app2email.com/docs/api/errors#invalid_to), [`ip_not_allowed`](https://www.app2email.com/docs/api/errors#ip_not_allowed), [`marketing_disabled_on_cloud_api`](https://www.app2email.com/docs/api/errors#marketing_disabled_on_cloud_api), [`marketing_per_user_limit`](https://www.app2email.com/docs/api/errors#marketing_per_user_limit), [`media_download_error`](https://www.app2email.com/docs/api/errors#media_download_error), [`media_download_failed`](https://www.app2email.com/docs/api/errors#media_download_failed), [`media_too_large`](https://www.app2email.com/docs/api/errors#media_too_large), [`media_type_not_allowed`](https://www.app2email.com/docs/api/errors#media_type_not_allowed), [`media_upload_error`](https://www.app2email.com/docs/api/errors#media_upload_error), [`media_upload_failed`](https://www.app2email.com/docs/api/errors#media_upload_failed), [`message_too_old`](https://www.app2email.com/docs/api/errors#message_too_old), [`messaging_limit_restricted`](https://www.app2email.com/docs/api/errors#messaging_limit_restricted), [`missing_api_key`](https://www.app2email.com/docs/api/errors#missing_api_key), [`missing_interactive`](https://www.app2email.com/docs/api/errors#missing_interactive), [`missing_media`](https://www.app2email.com/docs/api/errors#missing_media), [`missing_message_id`](https://www.app2email.com/docs/api/errors#missing_message_id), [`missing_template_language`](https://www.app2email.com/docs/api/errors#missing_template_language), [`missing_template_name`](https://www.app2email.com/docs/api/errors#missing_template_name), [`missing_text`](https://www.app2email.com/docs/api/errors#missing_text), [`monthly_cap_reached`](https://www.app2email.com/docs/api/errors#monthly_cap_reached), [`monthly_limit_reached`](https://www.app2email.com/docs/api/errors#monthly_limit_reached), [`number_already_verified`](https://www.app2email.com/docs/api/errors#number_already_verified), [`number_not_found`](https://www.app2email.com/docs/api/errors#number_not_found), [`outside_24h_window`](https://www.app2email.com/docs/api/errors#outside_24h_window), [`parameter_value_invalid`](https://www.app2email.com/docs/api/errors#parameter_value_invalid), [`plan_not_allowed`](https://www.app2email.com/docs/api/errors#plan_not_allowed), [`rate_limited`](https://www.app2email.com/docs/api/errors#rate_limited), [`reaction_too_old`](https://www.app2email.com/docs/api/errors#reaction_too_old), [`recipient_identity_changed`](https://www.app2email.com/docs/api/errors#recipient_identity_changed), [`recipient_in_experiment`](https://www.app2email.com/docs/api/errors#recipient_in_experiment), [`recipient_is_sender`](https://www.app2email.com/docs/api/errors#recipient_is_sender), [`recipient_not_allowed`](https://www.app2email.com/docs/api/errors#recipient_not_allowed), [`recipient_not_opted_in`](https://www.app2email.com/docs/api/errors#recipient_not_opted_in), [`recipient_opted_out`](https://www.app2email.com/docs/api/errors#recipient_opted_out), [`recipient_stopped_marketing`](https://www.app2email.com/docs/api/errors#recipient_stopped_marketing), [`recipient_unreachable`](https://www.app2email.com/docs/api/errors#recipient_unreachable), [`register_limit_reached`](https://www.app2email.com/docs/api/errors#register_limit_reached), [`request_too_large`](https://www.app2email.com/docs/api/errors#request_too_large), [`required_parameter_missing`](https://www.app2email.com/docs/api/errors#required_parameter_missing), [`schedule_failed`](https://www.app2email.com/docs/api/errors#schedule_failed), [`segment_and_recipients`](https://www.app2email.com/docs/api/errors#segment_and_recipients), [`segment_empty`](https://www.app2email.com/docs/api/errors#segment_empty), [`segment_not_found`](https://www.app2email.com/docs/api/errors#segment_not_found), [`send_at_in_past`](https://www.app2email.com/docs/api/errors#send_at_in_past), [`send_at_too_far`](https://www.app2email.com/docs/api/errors#send_at_too_far), [`service_not_live`](https://www.app2email.com/docs/api/errors#service_not_live), [`template_disabled`](https://www.app2email.com/docs/api/errors#template_disabled), [`template_format_policy`](https://www.app2email.com/docs/api/errors#template_format_policy), [`template_language_not_found`](https://www.app2email.com/docs/api/errors#template_language_not_found), [`template_lookup_failed`](https://www.app2email.com/docs/api/errors#template_lookup_failed), [`template_not_approved`](https://www.app2email.com/docs/api/errors#template_not_approved), [`template_not_found`](https://www.app2email.com/docs/api/errors#template_not_found), [`template_not_marketing`](https://www.app2email.com/docs/api/errors#template_not_marketing), [`template_parameter_count_mismatch`](https://www.app2email.com/docs/api/errors#template_parameter_count_mismatch), [`template_parameter_format_mismatch`](https://www.app2email.com/docs/api/errors#template_parameter_format_mismatch), [`template_parameter_invalid`](https://www.app2email.com/docs/api/errors#template_parameter_invalid), [`template_parameters_invalid`](https://www.app2email.com/docs/api/errors#template_parameters_invalid), [`template_paused`](https://www.app2email.com/docs/api/errors#template_paused), [`template_sample_media_failed`](https://www.app2email.com/docs/api/errors#template_sample_media_failed), [`template_text_too_long`](https://www.app2email.com/docs/api/errors#template_text_too_long), [`text_too_long`](https://www.app2email.com/docs/api/errors#text_too_long), [`to_and_recipients`](https://www.app2email.com/docs/api/errors#to_and_recipients), [`too_many_messages_to_recipient`](https://www.app2email.com/docs/api/errors#too_many_messages_to_recipient), [`too_many_recipients`](https://www.app2email.com/docs/api/errors#too_many_recipients), [`unsupported_content_type`](https://www.app2email.com/docs/api/errors#unsupported_content_type), [`unsupported_message_type`](https://www.app2email.com/docs/api/errors#unsupported_message_type), [`username_account_not_linked`](https://www.app2email.com/docs/api/errors#username_account_not_linked), [`username_change_limit`](https://www.app2email.com/docs/api/errors#username_change_limit), [`username_not_available`](https://www.app2email.com/docs/api/errors#username_not_available), [`username_not_eligible`](https://www.app2email.com/docs/api/errors#username_not_eligible), [`username_taken`](https://www.app2email.com/docs/api/errors#username_taken), [`voice_needs_ogg_opus`](https://www.app2email.com/docs/api/errors#voice_needs_ogg_opus), [`whatsapp_account_locked`](https://www.app2email.com/docs/api/errors#whatsapp_account_locked), [`whatsapp_account_restricted`](https://www.app2email.com/docs/api/errors#whatsapp_account_restricted), [`whatsapp_connection_problem`](https://www.app2email.com/docs/api/errors#whatsapp_connection_problem), [`whatsapp_error`](https://www.app2email.com/docs/api/errors#whatsapp_error), [`whatsapp_maintenance`](https://www.app2email.com/docs/api/errors#whatsapp_maintenance), [`whatsapp_number_not_registered`](https://www.app2email.com/docs/api/errors#whatsapp_number_not_registered), [`whatsapp_parameter_error`](https://www.app2email.com/docs/api/errors#whatsapp_parameter_error), [`whatsapp_payment_issue`](https://www.app2email.com/docs/api/errors#whatsapp_payment_issue), [`whatsapp_rate_limit`](https://www.app2email.com/docs/api/errors#whatsapp_rate_limit), [`whatsapp_unavailable`](https://www.app2email.com/docs/api/errors#whatsapp_unavailable)

## Webhook events it causes

`broadcast.completed`, `message.failed`, `message.held_for_approval`, `message.status`, `usage.threshold`

## Example

```bash
curl -X POST "https://api.app2email.com/v1/YOUR_NUMBER/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "#1234" }
        ]
      }
    ]
  }
}'
```

## 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}/messages": {
      "post": {
        "tags": [
          "Messages"
        ],
        "operationId": "sendTemplateMessage",
        "summary": "Send a WhatsApp message: template, or free-form reply",
        "description": "Sends one approved template to one recipient, or to several when `to` lists several numbers (or `recipients` gives each number its own values). The parameters are checked against the template before sending; on a mismatch the error includes a complete, correct `example_request` for that template. Nothing is sent when the request itself is invalid. `dry_run` checks without sending; `background` answers 202 and sends after; `send_at` schedules it (202, status scheduled). `type` text, image, video, document or interactive sends a free-form message to one contact within 24 hours of the contact's last message (422 outside_24h_window otherwise). `segment` sends a template to a saved segment's contacts. A business-scoped user id works wherever a number does. Also `audio`, `sticker`, `location`, `contacts`, `reaction` and the newer interactive kinds; template carousels, limited-time offers, catalog, MPM, SPM, flow and OTP buttons. `callback_data` comes back in message.status. MARKETING templates follow `marketing_api` / messages.marketing_route (`sent_via` in the answer).",
        "parameters": [
          {
            "$ref": "#/components/parameters/Number"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional. A unique value for this message or list (eg a UUID). The same request with the same key within 24 hours gets the first answer again, and nothing is sent twice. Ignored by dry runs.",
            "schema": {
              "type": "string",
              "maxLength": 255,
              "example": "order-1234-shipped"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTemplateRequest"
              },
              "examples": {
                "text_parameters": {
                  "summary": "Body with two text values",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "order_update",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "John"
                            },
                            {
                              "type": "text",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "image_header_link": {
                  "summary": "Image header from a link, plus a URL button value",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "new_arrivals",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/photo.jpg"
                              }
                            }
                          ]
                        },
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "John"
                            }
                          ]
                        },
                        {
                          "type": "button",
                          "sub_type": "url",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "summer-sale"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "document_header_base64": {
                  "summary": "PDF header sent as base64 in the request",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "invoice_ready",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "document",
                              "document": {
                                "data": "JVBERi0xLjQKJ...",
                                "filename": "invoice-1234.pdf"
                              }
                            }
                          ]
                        },
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "named_parameters": {
                  "summary": "Template with named placeholders",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "welcome",
                      "language": {
                        "code": "en_US"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "parameter_name": "first_name",
                              "text": "John"
                            },
                            {
                              "type": "text",
                              "parameter_name": "code",
                              "text": "X7Q2"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "several_numbers": {
                  "summary": "Same message to several numbers",
                  "value": {
                    "to": "61412345678,61498765432,61400111222",
                    "type": "template",
                    "campaign_name": "Order updates 21 Oct",
                    "template": {
                      "name": "order_update",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "John"
                            },
                            {
                              "type": "text",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "values_per_number": {
                  "summary": "Each number with its own values (recipients)",
                  "value": {
                    "type": "template",
                    "campaign_name": "Order updates",
                    "template": {
                      "name": "order_update",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/photo.jpg"
                              }
                            }
                          ]
                        }
                      ]
                    },
                    "recipients": [
                      {
                        "to": "61412345678",
                        "components": [
                          {
                            "type": "body",
                            "parameters": [
                              {
                                "type": "text",
                                "text": "John"
                              },
                              {
                                "type": "text",
                                "text": "#1234"
                              }
                            ]
                          }
                        ]
                      },
                      {
                        "to": "61498765432",
                        "components": [
                          {
                            "type": "body",
                            "parameters": [
                              {
                                "type": "text",
                                "text": "Mary"
                              },
                              {
                                "type": "text",
                                "text": "#1235"
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  }
                },
                "dry_run": {
                  "summary": "Check everything without sending",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "order_update",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "John"
                            },
                            {
                              "type": "text",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    },
                    "dry_run": true
                  }
                },
                "background": {
                  "summary": "Big list: answer now, send after",
                  "value": {
                    "to": "61412345678,61498765432,61400111222",
                    "type": "template",
                    "campaign_name": "October newsletter",
                    "background": true,
                    "template": {
                      "name": "october_newsletter",
                      "language": {
                        "code": "en"
                      }
                    }
                  }
                },
                "free_text_reply": {
                  "summary": "Free-form text reply (within 24 hours)",
                  "value": {
                    "to": "61412345678",
                    "type": "text",
                    "text": {
                      "body": "Thanks, it arrives on Friday.",
                      "preview_url": false
                    }
                  }
                },
                "free_image_reply": {
                  "summary": "Free-form image from a link, with a caption",
                  "value": {
                    "to": "61412345678",
                    "type": "image",
                    "image": {
                      "link": "https://example.com/photo.jpg",
                      "caption": "Your parcel"
                    }
                  }
                },
                "free_document_reply": {
                  "summary": "Free-form PDF as base64, quoting a message",
                  "value": {
                    "to": "61412345678",
                    "type": "document",
                    "reply_to": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                    "document": {
                      "data": "JVBERi0xLjQKJ...",
                      "filename": "invoice-1234.pdf",
                      "caption": "Invoice #1234"
                    }
                  }
                },
                "scheduled": {
                  "summary": "Several numbers, sent at a set time",
                  "value": {
                    "to": "61412345678,61498765432,61400111222",
                    "type": "template",
                    "campaign_name": "Order updates 2 Nov",
                    "template": {
                      "name": "order_update",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "John"
                            },
                            {
                              "type": "text",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    },
                    "send_at": "2026-11-02T09:00:00+11:00"
                  }
                },
                "interactive_buttons": {
                  "summary": "Reply buttons (within 24 hours)",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "button",
                      "body": {
                        "text": "Confirm your booking for Friday 10:00?"
                      },
                      "action": {
                        "buttons": [
                          {
                            "type": "reply",
                            "reply": {
                              "id": "yes",
                              "title": "Confirm"
                            }
                          },
                          {
                            "type": "reply",
                            "reply": {
                              "id": "no",
                              "title": "Change"
                            }
                          }
                        ]
                      }
                    }
                  }
                },
                "interactive_list": {
                  "summary": "A list to pick from (within 24 hours)",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "list",
                      "body": {
                        "text": "Which time suits you?"
                      },
                      "action": {
                        "button": "Pick a time",
                        "sections": [
                          {
                            "title": "Friday",
                            "rows": [
                              {
                                "id": "fri10",
                                "title": "10:00"
                              },
                              {
                                "id": "fri14",
                                "title": "14:00",
                                "description": "afternoon"
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                },
                "business_scoped_user_id": {
                  "summary": "A contact known by a business-scoped user id",
                  "value": {
                    "recipient": "61.AbC123xyz",
                    "type": "text",
                    "text": {
                      "body": "Thanks, it arrives on Friday."
                    }
                  }
                },
                "segment": {
                  "summary": "A template to a saved segment, values from each contact",
                  "value": {
                    "segment": "VIP, consented",
                    "type": "template",
                    "campaign_name": "November offer",
                    "template": {
                      "name": "november_offer",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "parameter_name": "first_name"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_text": {
                  "summary": "Text",
                  "value": {
                    "to": "61412345678",
                    "type": "text",
                    "text": {
                      "body": "Your order has shipped.",
                      "preview_url": false
                    }
                  }
                },
                "type_image": {
                  "summary": "Image",
                  "value": {
                    "to": "61412345678",
                    "type": "image",
                    "image": {
                      "link": "https://example.com/photo.jpg",
                      "caption": "Your parcel"
                    }
                  }
                },
                "type_video": {
                  "summary": "Video",
                  "value": {
                    "to": "61412345678",
                    "type": "video",
                    "video": {
                      "link": "https://example.com/howto.mp4",
                      "caption": "How to set it up"
                    }
                  }
                },
                "type_document": {
                  "summary": "Document",
                  "value": {
                    "to": "61412345678",
                    "type": "document",
                    "document": {
                      "link": "https://example.com/invoice-1234.pdf",
                      "filename": "invoice-1234.pdf",
                      "caption": "Invoice"
                    }
                  }
                },
                "type_audio": {
                  "summary": "Audio and voice message",
                  "value": {
                    "to": "61412345678",
                    "type": "audio",
                    "audio": {
                      "id": "1013859600285441",
                      "voice": true
                    }
                  }
                },
                "type_sticker": {
                  "summary": "Sticker",
                  "value": {
                    "to": "61412345678",
                    "type": "sticker",
                    "sticker": {
                      "link": "https://example.com/stickers/thanks.webp"
                    }
                  }
                },
                "type_location": {
                  "summary": "Location",
                  "value": {
                    "to": "61412345678",
                    "type": "location",
                    "location": {
                      "latitude": -33.8568,
                      "longitude": 151.2153,
                      "name": "Sydney Opera House",
                      "address": "Bennelong Point, Sydney NSW 2000"
                    }
                  }
                },
                "type_contacts": {
                  "summary": "Contact card",
                  "value": {
                    "to": "61412345678",
                    "type": "contacts",
                    "contacts": [
                      {
                        "name": {
                          "formatted_name": "Jane Citizen",
                          "first_name": "Jane",
                          "last_name": "Citizen"
                        },
                        "phones": [
                          {
                            "phone": "+61 412 345 678",
                            "type": "CELL",
                            "wa_id": "61412345678"
                          }
                        ],
                        "emails": [
                          {
                            "email": "jane@example.com",
                            "type": "WORK"
                          }
                        ],
                        "org": {
                          "company": "Example Pty Ltd"
                        }
                      }
                    ]
                  }
                },
                "type_reaction": {
                  "summary": "Reaction",
                  "value": {
                    "to": "61412345678",
                    "type": "reaction",
                    "reaction": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
                      "emoji": "👍"
                    }
                  }
                },
                "type_button": {
                  "summary": "Reply buttons",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "button",
                      "body": {
                        "text": "Confirm your booking for Friday 10:00?"
                      },
                      "action": {
                        "buttons": [
                          {
                            "type": "reply",
                            "reply": {
                              "id": "yes",
                              "title": "Confirm"
                            }
                          },
                          {
                            "type": "reply",
                            "reply": {
                              "id": "no",
                              "title": "Change"
                            }
                          }
                        ]
                      }
                    }
                  }
                },
                "type_list": {
                  "summary": "List",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "list",
                      "body": {
                        "text": "Which time suits you?"
                      },
                      "action": {
                        "button": "Times",
                        "sections": [
                          {
                            "title": "Friday",
                            "rows": [
                              {
                                "id": "fri10",
                                "title": "10:00"
                              },
                              {
                                "id": "fri11",
                                "title": "11:00"
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                },
                "type_cta_url": {
                  "summary": "URL button",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "cta_url",
                      "body": {
                        "text": "Your invoice is ready."
                      },
                      "action": {
                        "name": "cta_url",
                        "parameters": {
                          "display_text": "Open invoice",
                          "url": "https://example.com/invoice/1234"
                        }
                      }
                    }
                  }
                },
                "type_carousel": {
                  "summary": "Media carousel",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "carousel",
                      "body": {
                        "text": "Three of our latest arrivals, each under $25:"
                      },
                      "action": {
                        "cards": [
                          {
                            "card_index": 0,
                            "type": "cta_url",
                            "header": {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/img/echeveria.jpg"
                              }
                            },
                            "body": {
                              "text": "*Blue Echeveria*"
                            },
                            "action": {
                              "name": "cta_url",
                              "parameters": {
                                "display_text": "Buy now",
                                "url": "https://shop.example.com/echeveria"
                              }
                            }
                          },
                          {
                            "card_index": 1,
                            "type": "cta_url",
                            "header": {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/img/haworthia.jpg"
                              }
                            },
                            "body": {
                              "text": "*Zebra Haworthia*"
                            },
                            "action": {
                              "name": "cta_url",
                              "parameters": {
                                "display_text": "Buy now",
                                "url": "https://shop.example.com/haworthia"
                              }
                            }
                          }
                        ]
                      }
                    }
                  }
                },
                "type_product_carousel": {
                  "summary": "Product carousel",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "carousel",
                      "body": {
                        "text": "Picked for you this week:"
                      },
                      "action": {
                        "cards": [
                          {
                            "card_index": 0,
                            "type": "product",
                            "action": {
                              "product_retailer_id": "SKU-1234",
                              "catalog_id": "194836987003835"
                            }
                          },
                          {
                            "card_index": 1,
                            "type": "product",
                            "action": {
                              "product_retailer_id": "SKU-5678",
                              "catalog_id": "194836987003835"
                            }
                          }
                        ]
                      }
                    }
                  }
                },
                "type_location_request_message": {
                  "summary": "Location request",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "location_request_message",
                      "body": {
                        "text": "Where should we pick you up? Tap to share your location."
                      },
                      "action": {
                        "name": "send_location"
                      }
                    }
                  }
                },
                "type_request_contact_info": {
                  "summary": "Contact info request",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "request_contact_info",
                      "body": {
                        "text": "Please share your phone number so we can call you back."
                      },
                      "action": {
                        "name": "request_contact_info"
                      }
                    }
                  }
                },
                "type_flow": {
                  "summary": "Flow",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "flow",
                      "header": {
                        "type": "text",
                        "text": "Book a table"
                      },
                      "body": {
                        "text": "Pick a day and time."
                      },
                      "action": {
                        "name": "flow",
                        "parameters": {
                          "flow_message_version": "3",
                          "flow_id": "1234567890123456",
                          "flow_cta": "Book now",
                          "flow_token": "booking-5521",
                          "flow_action": "navigate",
                          "flow_action_payload": {
                            "screen": "WELCOME"
                          }
                        }
                      }
                    }
                  }
                },
                "type_product": {
                  "summary": "Single product",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "product",
                      "body": {
                        "text": "The one you asked about:"
                      },
                      "action": {
                        "catalog_id": "194836987003835",
                        "product_retailer_id": "SKU-1234"
                      }
                    }
                  }
                },
                "type_product_list": {
                  "summary": "Product list",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "product_list",
                      "header": {
                        "type": "text",
                        "text": "Our picks"
                      },
                      "body": {
                        "text": "Popular this week."
                      },
                      "action": {
                        "catalog_id": "194836987003835",
                        "sections": [
                          {
                            "title": "Succulents",
                            "product_items": [
                              {
                                "product_retailer_id": "SKU-1234"
                              },
                              {
                                "product_retailer_id": "SKU-5678"
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                },
                "type_catalog_message": {
                  "summary": "Catalog",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "catalog_message",
                      "body": {
                        "text": "Browse our catalog."
                      },
                      "action": {
                        "name": "catalog_message",
                        "parameters": {
                          "thumbnail_product_retailer_id": "SKU-1234"
                        }
                      }
                    }
                  }
                },
                "type_call_permission_request": {
                  "summary": "Call permission request",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "call_permission_request",
                      "body": {
                        "text": "May we call you on WhatsApp about your order?"
                      },
                      "action": {
                        "name": "call_permission_request"
                      }
                    }
                  }
                },
                "type_voice_call": {
                  "summary": "Call button",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "voice_call",
                      "body": {
                        "text": "Questions? Call us on WhatsApp."
                      },
                      "action": {
                        "name": "voice_call",
                        "parameters": {
                          "display_text": "Call us",
                          "ttl_minutes": 60
                        }
                      }
                    }
                  }
                },
                "type_address_message": {
                  "summary": "Address request",
                  "value": {
                    "to": "919876543210",
                    "type": "interactive",
                    "interactive": {
                      "type": "address_message",
                      "body": {
                        "text": "Where should we deliver?"
                      },
                      "action": {
                        "name": "address_message",
                        "parameters": {
                          "country": "IN"
                        }
                      }
                    }
                  }
                },
                "type_order_details": {
                  "summary": "Order details",
                  "value": {
                    "to": "919876543210",
                    "type": "interactive",
                    "interactive": {
                      "type": "order_details",
                      "body": {
                        "text": "Your order is ready to pay."
                      },
                      "action": {
                        "name": "review_and_pay",
                        "parameters": {
                          "reference_id": "ORDER-1234",
                          "type": "digital-goods",
                          "payment_type": "upi",
                          "payment_configuration": "my-config",
                          "currency": "INR",
                          "total_amount": {
                            "value": 21000,
                            "offset": 100
                          },
                          "order": {
                            "status": "pending",
                            "subtotal": {
                              "value": 21000,
                              "offset": 100
                            },
                            "items": [
                              {
                                "retailer_id": "SKU-1234",
                                "name": "Gift card",
                                "amount": {
                                  "value": 21000,
                                  "offset": 100
                                },
                                "quantity": 1
                              }
                            ]
                          }
                        }
                      }
                    }
                  }
                },
                "type_order_status": {
                  "summary": "Order status",
                  "value": {
                    "to": "919876543210",
                    "type": "interactive",
                    "interactive": {
                      "type": "order_status",
                      "body": {
                        "text": "Your order has shipped."
                      },
                      "action": {
                        "name": "review_order",
                        "parameters": {
                          "reference_id": "ORDER-1234",
                          "order": {
                            "status": "shipped",
                            "description": "Arrives Friday"
                          }
                        }
                      }
                    }
                  }
                },
                "type_template": {
                  "summary": "Template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "order_update",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "Jane"
                            },
                            {
                              "type": "text",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_named": {
                  "summary": "Template, named parameters",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "order_update_named",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "parameter_name": "first_name",
                              "text": "Jane"
                            },
                            {
                              "type": "text",
                              "parameter_name": "order_id",
                              "text": "#1234"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_location": {
                  "summary": "Template, location header",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "pickup_ready",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "location",
                              "location": {
                                "latitude": "-33.8568",
                                "longitude": "151.2153",
                                "name": "Our shop",
                                "address": "1 George St, Sydney"
                              }
                            }
                          ]
                        },
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "Jane"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_carousel": {
                  "summary": "Carousel template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "summer_succulents",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "Jane"
                            }
                          ]
                        },
                        {
                          "type": "carousel",
                          "cards": [
                            {
                              "card_index": 0,
                              "components": [
                                {
                                  "type": "header",
                                  "parameters": [
                                    {
                                      "type": "image",
                                      "image": {
                                        "link": "https://example.com/img/card0.jpg"
                                      }
                                    }
                                  ]
                                },
                                {
                                  "type": "button",
                                  "sub_type": "quick_reply",
                                  "index": "0",
                                  "parameters": [
                                    {
                                      "type": "payload",
                                      "payload": "more-0"
                                    }
                                  ]
                                },
                                {
                                  "type": "button",
                                  "sub_type": "url",
                                  "index": "1",
                                  "parameters": [
                                    {
                                      "type": "text",
                                      "text": "card-0"
                                    }
                                  ]
                                }
                              ]
                            },
                            {
                              "card_index": 1,
                              "components": [
                                {
                                  "type": "header",
                                  "parameters": [
                                    {
                                      "type": "image",
                                      "image": {
                                        "link": "https://example.com/img/card1.jpg"
                                      }
                                    }
                                  ]
                                },
                                {
                                  "type": "button",
                                  "sub_type": "quick_reply",
                                  "index": "0",
                                  "parameters": [
                                    {
                                      "type": "payload",
                                      "payload": "more-1"
                                    }
                                  ]
                                },
                                {
                                  "type": "button",
                                  "sub_type": "url",
                                  "index": "1",
                                  "parameters": [
                                    {
                                      "type": "text",
                                      "text": "card-1"
                                    }
                                  ]
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_product_carousel": {
                  "summary": "Product card carousel template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "product_picks",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "carousel",
                          "cards": [
                            {
                              "card_index": 0,
                              "components": [
                                {
                                  "type": "header",
                                  "parameters": [
                                    {
                                      "type": "product",
                                      "product": {
                                        "product_retailer_id": "SKU-1234",
                                        "catalog_id": "194836987003835"
                                      }
                                    }
                                  ]
                                }
                              ]
                            },
                            {
                              "card_index": 1,
                              "components": [
                                {
                                  "type": "header",
                                  "parameters": [
                                    {
                                      "type": "product",
                                      "product": {
                                        "product_retailer_id": "SKU-5678",
                                        "catalog_id": "194836987003835"
                                      }
                                    }
                                  ]
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_limited_time_offer": {
                  "summary": "Limited-time offer template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "flash_sale",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/img/sale.jpg"
                              }
                            }
                          ]
                        },
                        {
                          "type": "limited_time_offer",
                          "parameters": [
                            {
                              "type": "limited_time_offer",
                              "limited_time_offer": {
                                "expiration_time_ms": 1767225600000
                              }
                            }
                          ]
                        },
                        {
                          "type": "button",
                          "sub_type": "copy_code",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "coupon_code",
                              "coupon_code": "SAVE20"
                            }
                          ]
                        },
                        {
                          "type": "button",
                          "sub_type": "url",
                          "index": "1",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "summer"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_copy_code": {
                  "summary": "Coupon code template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "welcome_coupon",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "button",
                          "sub_type": "copy_code",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "coupon_code",
                              "coupon_code": "WELCOME10"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_catalog": {
                  "summary": "Catalog template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "browse_catalog",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "button",
                          "sub_type": "catalog",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "action",
                              "action": {
                                "thumbnail_product_retailer_id": "SKU-1234"
                              }
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_mpm": {
                  "summary": "Multi-product template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "new_arrivals",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "Succulents"
                            }
                          ]
                        },
                        {
                          "type": "button",
                          "sub_type": "mpm",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "action",
                              "action": {
                                "thumbnail_product_retailer_id": "SKU-1234",
                                "sections": [
                                  {
                                    "title": "Popular",
                                    "product_items": [
                                      {
                                        "product_retailer_id": "SKU-1234"
                                      },
                                      {
                                        "product_retailer_id": "SKU-5678"
                                      }
                                    ]
                                  }
                                ]
                              }
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_spm": {
                  "summary": "Single-product template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "product_of_the_week",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "header",
                          "parameters": [
                            {
                              "type": "product",
                              "product": {
                                "product_retailer_id": "SKU-1234",
                                "catalog_id": "194836987003835"
                              }
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_flow": {
                  "summary": "Flow button template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "book_a_table",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "button",
                          "sub_type": "flow",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "action",
                              "action": {
                                "flow_token": "booking-5521",
                                "flow_action_data": {
                                  "party_size": 2
                                }
                              }
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_otp": {
                  "summary": "One-time password template",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "login_code",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "482913"
                            }
                          ]
                        },
                        {
                          "type": "button",
                          "sub_type": "url",
                          "index": "0",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "482913"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "type_template_marketing_messages_api": {
                  "summary": "Marketing template via the Marketing Messages API",
                  "value": {
                    "to": "61412345678",
                    "type": "template",
                    "template": {
                      "name": "november_offer",
                      "language": {
                        "code": "en"
                      },
                      "components": [
                        {
                          "type": "body",
                          "parameters": [
                            {
                              "type": "text",
                              "text": "Jane"
                            }
                          ]
                        }
                      ]
                    },
                    "marketing_api": "mm_api",
                    "product_policy": "CLOUD_API_FALLBACK",
                    "message_activity_sharing": true,
                    "callback_data": "campaign-nov"
                  }
                },
                "type_mark_read": {
                  "summary": "Mark as read and typing",
                  "value": {
                    "messaging_product": "whatsapp",
                    "status": "read",
                    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
                    "typing_indicator": {
                      "type": "text"
                    }
                  }
                },
                "meta_exact_body": {
                  "summary": "Meta's own body, unchanged",
                  "value": {
                    "messaging_product": "whatsapp",
                    "recipient_type": "individual",
                    "to": "+61412345678",
                    "type": "text",
                    "text": {
                      "preview_url": false,
                      "body": "Your order has shipped."
                    },
                    "biz_opaque_callback_data": "order-1234"
                  }
                },
                "callback_data": {
                  "summary": "callback_data, back in message.status",
                  "value": {
                    "to": "61412345678",
                    "type": "text",
                    "text": {
                      "body": "Your table is booked for 7 pm."
                    },
                    "callback_data": "booking-5521"
                  }
                },
                "reaction_remove": {
                  "summary": "Remove a reaction",
                  "value": {
                    "to": "61412345678",
                    "type": "reaction",
                    "reaction": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
                      "emoji": ""
                    }
                  }
                },
                "audio_link": {
                  "summary": "Audio file from a link",
                  "value": {
                    "to": "61412345678",
                    "type": "audio",
                    "audio": {
                      "link": "https://example.com/audio/welcome.mp3"
                    }
                  }
                },
                "carousel_quick_replies": {
                  "summary": "Carousel with quick-reply buttons",
                  "value": {
                    "to": "61412345678",
                    "type": "interactive",
                    "interactive": {
                      "type": "carousel",
                      "body": {
                        "text": "Which one do you like?"
                      },
                      "action": {
                        "cards": [
                          {
                            "card_index": 0,
                            "header": {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/img/plant0.jpg"
                              }
                            },
                            "action": {
                              "buttons": [
                                {
                                  "type": "quick_reply",
                                  "quick_reply": {
                                    "id": "more-0",
                                    "title": "More like this"
                                  }
                                }
                              ]
                            }
                          },
                          {
                            "card_index": 1,
                            "header": {
                              "type": "image",
                              "image": {
                                "link": "https://example.com/img/plant1.jpg"
                              }
                            },
                            "action": {
                              "buttons": [
                                {
                                  "type": "quick_reply",
                                  "quick_reply": {
                                    "id": "more-1",
                                    "title": "More like this"
                                  }
                                }
                              ]
                            }
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted by WhatsApp (all numbers, when several were given). A dry run also answers 200. A free-form message answers 200 too. A sandbox key answers 200 with sandbox: true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponse"
                },
                "example": {
                  "success": true,
                  "request_id": "kxrkf",
                  "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                  "status": "accepted",
                  "from": "4976659348270",
                  "to": "61412345678",
                  "template": {
                    "name": "order_update",
                    "language": "en",
                    "category": "UTILITY"
                  },
                  "text": "Hi John, your order #1234 has shipped.",
                  "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_...",
                  "note": "accepted by WhatsApp. delivery and read status appear in your app2email Activity Log (WhatsApp sent).",
                  "contacts": [
                    {
                      "input": "61412345678",
                      "wa_id": "61412345678"
                    }
                  ]
                }
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "description": "true when this is the stored answer of an earlier request with the same Idempotency-Key.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "\"background\": true - checked, and sending has started (progress: broadcast.status_url). Or \"send_at\" - status scheduled, sent at scheduled_for (cancel with POST /broadcasts/{code}/cancel). Or status pending_approval: held by the key's approval gate until a person approves it (approval.url). The example is the background answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponse"
                },
                "example": {
                  "success": true,
                  "request_id": "t7wpe",
                  "status": "queued",
                  "from": "4976659348270",
                  "template": {
                    "name": "october_newsletter",
                    "language": "en",
                    "category": "MARKETING"
                  },
                  "broadcast": {
                    "name": "October newsletter",
                    "code": "k3XbQ9rTzP2mWv7a1c9e",
                    "report_url": "https://www.app2email.com/dashboard/log/broadcast/k3XbQ9rTzP2mWv7a1c9e",
                    "status_url": "https://api.app2email.com/v1/4976659348270/broadcasts/k3XbQ9rTzP2mWv7a1c9e"
                  },
                  "recipients": 3,
                  "queued": 3,
                  "skipped": 0,
                  "results": [],
                  "note": "Sending in the background. GET broadcast.status_url for progress and the result for each number, or use the broadcast.completed webhook."
                }
              }
            }
          },
          "207": {
            "description": "Several numbers: some were accepted, some not. 'results' has the outcome per number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponse"
                },
                "example": {
                  "success": false,
                  "request_id": "q8m2d",
                  "status": "partially_accepted",
                  "from": "4976659348270",
                  "template": {
                    "name": "order_update",
                    "language": "en",
                    "category": "UTILITY"
                  },
                  "text": "Hi John, your order #1234 has shipped.",
                  "broadcast": {
                    "name": "Order updates 21 Oct",
                    "code": "k3XbQ9rTzP2mWv7a1c9e",
                    "report_url": "https://www.app2email.com/dashboard/log/broadcast/k3XbQ9rTzP2mWv7a1c9e"
                  },
                  "recipients": 3,
                  "accepted": 2,
                  "failed": 1,
                  "results": [
                    {
                      "to": "61412345678",
                      "success": true,
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
                      "status": "accepted",
                      "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_..."
                    },
                    {
                      "to": "61498765432",
                      "success": true,
                      "message_id": "wamid.HBgLNjE0OTg3NjU0MzIVAgARGBJTQU1QTEVfT1VUQk9VTkQwMgA=",
                      "status": "accepted",
                      "conversation_url": "https://www.app2email.com/conversation/61498765432_4976659348270_..."
                    },
                    {
                      "to": "61400111222",
                      "success": false,
                      "error": {
                        "code": "recipient_unreachable",
                        "message": "WhatsApp did not send the message: ...",
                        "how_to_fix": "WhatsApp could not deliver to this number. Check it is a WhatsApp number written with its country code ..."
                      }
                    }
                  ],
                  "note": "accepted by WhatsApp. delivery and read status appear in your app2email Activity Log under Broadcasts (broadcast.report_url)."
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "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"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
            "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"
                }
              }
            }
          },
          "422": {
            "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
            "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"
                }
              }
            }
          },
          "502": {
            "description": "WhatsApp (Meta) returned an error or could not be reached. Possible error.code values: template_lookup_failed, media_upload_failed, template_sample_media_failed, template_delete_failed, whatsapp_error, block_users_error, account_service_error, payment_link_failed, email_not_sent, flow_json_download_failed, media_lookup_failed, media_delete_failed, marketing_status_lookup_failed, contact_book_error, profile_photo_failed, payment_provider_error, shop_payment_failed, whatsapp_flow_failed, connection_failed.",
            "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-scope": "messages:send",
        "x-a2e-sandbox": "simulated",
        "x-a2e-error-codes": [
          "api_key_expired",
          "api_key_number_mismatch",
          "api_key_old_format",
          "api_key_revoked",
          "approval_body_too_large",
          "background_start_failed",
          "block_list_busy",
          "block_list_full",
          "block_users_error",
          "block_users_failed",
          "broadcast_cancelled",
          "bsuid_not_supported",
          "call_permission_required",
          "caption_not_supported",
          "caption_too_long",
          "daily_cap_reached",
          "display_name_not_approved",
          "duplicate_recipients",
          "free_form_single_recipient",
          "idempotency_key_reused",
          "idempotency_request_in_progress",
          "idempotency_request_interrupted",
          "insufficient_scope",
          "internal_error",
          "invalid_api_key",
          "invalid_authorization_header",
          "invalid_base64",
          "invalid_callback_data",
          "invalid_components",
          "invalid_contacts_message",
          "invalid_cursor",
          "invalid_idempotency_key",
          "invalid_identity_key_hash",
          "invalid_interactive",
          "invalid_json",
          "invalid_location",
          "invalid_marketing_api",
          "invalid_media_link",
          "invalid_number_in_url",
          "invalid_reaction",
          "invalid_recipients",
          "invalid_reply_to",
          "invalid_send_at",
          "invalid_to",
          "ip_not_allowed",
          "marketing_disabled_on_cloud_api",
          "marketing_per_user_limit",
          "media_download_error",
          "media_download_failed",
          "media_too_large",
          "media_type_not_allowed",
          "media_upload_error",
          "media_upload_failed",
          "message_too_old",
          "messaging_limit_restricted",
          "missing_api_key",
          "missing_interactive",
          "missing_media",
          "missing_message_id",
          "missing_template_language",
          "missing_template_name",
          "missing_text",
          "monthly_cap_reached",
          "monthly_limit_reached",
          "number_already_verified",
          "number_not_found",
          "outside_24h_window",
          "parameter_value_invalid",
          "plan_not_allowed",
          "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",
          "register_limit_reached",
          "request_too_large",
          "required_parameter_missing",
          "schedule_failed",
          "segment_and_recipients",
          "segment_empty",
          "segment_not_found",
          "send_at_in_past",
          "send_at_too_far",
          "service_not_live",
          "template_disabled",
          "template_format_policy",
          "template_language_not_found",
          "template_lookup_failed",
          "template_not_approved",
          "template_not_found",
          "template_not_marketing",
          "template_parameter_count_mismatch",
          "template_parameter_format_mismatch",
          "template_parameter_invalid",
          "template_parameters_invalid",
          "template_paused",
          "template_sample_media_failed",
          "template_text_too_long",
          "text_too_long",
          "to_and_recipients",
          "too_many_messages_to_recipient",
          "too_many_recipients",
          "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",
          "whatsapp_account_locked",
          "whatsapp_account_restricted",
          "whatsapp_connection_problem",
          "whatsapp_error",
          "whatsapp_maintenance",
          "whatsapp_number_not_registered",
          "whatsapp_parameter_error",
          "whatsapp_payment_issue",
          "whatsapp_rate_limit",
          "whatsapp_unavailable"
        ],
        "x-a2e-webhook-events": [
          "broadcast.completed",
          "message.failed",
          "message.held_for_approval",
          "message.status",
          "usage.threshold"
        ],
        "x-a2e-mcp-tool": "send_template",
        "x-a2e-mcp-tools": [
          "send_template",
          "send_text",
          "send_media",
          "send_interactive",
          "send_message",
          "send_reaction",
          "send_location"
        ],
        "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)."
          }
        }
      },
      "RecipientResult": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "example": "61412345678"
          },
          "success": {
            "type": "boolean"
          },
          "message_id": {
            "type": "string",
            "description": "WhatsApp message id, when accepted."
          },
          "status": {
            "type": "string",
            "enum": [
              "accepted"
            ]
          },
          "text": {
            "type": "string",
            "description": "This number's message text, when the numbers had different values ('recipients')."
          },
          "conversation_url": {
            "type": "string"
          },
          "error": {
            "$ref": "#/components/schemas/Error",
            "description": "Why this number was not sent, eg recipient_opted_out, monthly_limit_reached, recipient_unreachable."
          },
          "would_send": {
            "type": "boolean",
            "description": "Dry run only."
          },
          "whatsapp_message": {
            "type": "object",
            "additionalProperties": true,
            "description": "Dry run only: the exact message WhatsApp would get."
          },
          "whatsapp_status": {
            "type": "string"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SendContact"
            }
          },
          "sent_via": {
            "type": "string",
            "enum": [
              "cloud_api",
              "mm_api"
            ]
          }
        }
      },
      "SendContact": {
        "type": "object",
        "description": "WhatsApp's contacts[] of the send answer.",
        "properties": {
          "input": {
            "type": "string",
            "example": "61412345678"
          },
          "wa_id": {
            "type": "string",
            "example": "61412345678"
          },
          "user_id": {
            "type": "string",
            "example": "AU.13491208655302741918",
            "description": "The business-scoped user id, when WhatsApp gives one."
          }
        }
      },
      "SendMessageResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "request_id": {
            "type": "string",
            "example": "kxrkf"
          },
          "message_id": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
            "description": "WhatsApp message id."
          },
          "status": {
            "type": "string",
            "enum": [
              "accepted",
              "partially_accepted",
              "failed",
              "queued",
              "scheduled",
              "dry_run",
              "pending_approval"
            ],
            "description": "accepted: accepted by WhatsApp (delivered/read status: GET /messages/{message_id} or the message.status webhook). partially_accepted / failed: a list where some / none were accepted. queued: background send started (HTTP 202). scheduled: 'send_at' given, sending later (HTTP 202; scheduled_for and the broadcast code). dry_run: a test, nothing sent. pending_approval: held by the key's approval gate (HTTP 202; 'approval' has the id and url)."
          },
          "sandbox": {
            "type": "boolean",
            "description": "true: a sandbox key simulated the send; nothing went to WhatsApp (message ids start with wamid.SANDBOX.)."
          },
          "approval": {
            "type": "object",
            "description": "status pending_approval only.",
            "properties": {
              "id": {
                "type": "string",
                "example": "apr_a1b2c3d4e5f6g7h8"
              },
              "url": {
                "type": "string",
                "description": "The dashboard page to approve or reject it."
              },
              "expires": {
                "type": "string",
                "format": "date-time"
              },
              "recipients": {
                "type": "integer"
              },
              "key": {
                "type": "string"
              }
            }
          },
          "summary": {
            "type": "object",
            "additionalProperties": true,
            "description": "status pending_approval only: what was held (recipients, template, text)."
          },
          "type": {
            "type": "string",
            "enum": [
              "template",
              "text",
              "image",
              "video",
              "document",
              "interactive",
              "audio",
              "sticker",
              "location",
              "contacts",
              "reaction"
            ],
            "description": "Free-form replies: the message type. Templates: 'template'."
          },
          "from": {
            "type": "string",
            "example": "4976659348270"
          },
          "to": {
            "type": "string",
            "example": "61412345678"
          },
          "window_closes_at": {
            "type": "string",
            "format": "date-time",
            "description": "Free-form replies: when the 24 hour window closes (after the contact's last message)."
          },
          "scheduled_for": {
            "type": "string",
            "format": "date-time",
            "description": "send_at only: when the send starts (UTC)."
          },
          "scheduled": {
            "type": "integer",
            "description": "send_at only: how many messages are scheduled."
          },
          "template": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "category": {
                "type": "string"
              }
            }
          },
          "text": {
            "type": "string",
            "description": "The message text with your values filled in."
          },
          "media": {
            "type": "string",
            "description": "The header media sent, if any."
          },
          "conversation_url": {
            "type": "string",
            "description": "Conversation history page on app2email.com."
          },
          "note": {
            "type": "string"
          },
          "broadcast": {
            "type": "object",
            "description": "Several numbers in 'to' only: the broadcast this list is recorded as.",
            "properties": {
              "name": {
                "type": "string",
                "example": "October newsletter"
              },
              "code": {
                "type": "string"
              },
              "report_url": {
                "type": "string",
                "description": "The broadcast's report page on app2email.com, with delivered/read counts per number."
              },
              "status_url": {
                "type": "string",
                "description": "GET it (with your API key) for the broadcast's status and the result per number."
              }
            }
          },
          "recipients": {
            "type": "integer",
            "description": "Several numbers in 'to' only: how many different numbers were given."
          },
          "accepted": {
            "type": "integer",
            "description": "Several numbers only: how many messages WhatsApp accepted."
          },
          "failed": {
            "type": "integer",
            "description": "Several numbers only: how many were not sent (see results)."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecipientResult"
            },
            "description": "Several numbers only: one entry per number, in the order given."
          },
          "error": {
            "$ref": "#/components/schemas/Error",
            "description": "Several numbers only, when none were sent: the first number's error."
          },
          "queued": {
            "type": "integer",
            "description": "Background send (HTTP 202): how many messages will be sent."
          },
          "skipped": {
            "type": "integer",
            "description": "Background send: how many numbers are skipped (listed in results, eg Do Not Call list)."
          },
          "dry_run": {
            "type": "boolean",
            "description": "Dry run only: true."
          },
          "would_send": {
            "type": "integer",
            "description": "Dry run only: how many messages would be sent."
          },
          "would_skip": {
            "type": "integer",
            "description": "Dry run only: how many numbers would be skipped (see results)."
          },
          "messages_left_this_month": {
            "type": "integer",
            "description": "Dry run only: messages left this billing month (the plan limit covers outgoing WhatsApp + outgoing emails)."
          },
          "broadcast_name": {
            "type": "string",
            "description": "Dry run of a list: the name the broadcast would get."
          },
          "whatsapp_status": {
            "type": "string",
            "enum": [
              "accepted",
              "held_for_quality_assessment",
              "paused"
            ],
            "description": "WhatsApp's own message_status for paced templates: held_for_quality_assessment = WhatsApp holds it while it checks the template's quality (it may be dropped later, 132015). Not app2email's approval gate."
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SendContact"
            },
            "description": "WhatsApp's contacts[]: the wa_id and business-scoped user_id it resolved."
          },
          "sent_via": {
            "type": "string",
            "enum": [
              "cloud_api",
              "mm_api"
            ],
            "description": "MARKETING templates: the path used (cloud_api = /messages, mm_api = the Marketing Messages API). Dry run: the path it would take."
          },
          "whatsapp_edge": {
            "type": "string",
            "enum": [
              "messages",
              "marketing_messages"
            ],
            "description": "Dry run of a template: the WhatsApp endpoint the message would go to."
          }
        }
      },
      "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"
          }
        }
      },
      "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>"
      }
    }
  }
}
```

