# Change the WhatsApp business profile

HTML: https://www.app2email.com/docs/api/number/update-business-profile · Index: https://www.app2email.com/docs/api/llms.txt

`PATCH https://api.app2email.com/v1/{number}/profile`

Fields left out stay as they are. Meta's own body (with messaging_product, profile_picture_handle) works unchanged.

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

## Parameters

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

## Body

`application/json`, required

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `about` | string |  | 1–139 chars |
| `address` | string |  | max 256 chars |
| `description` | string |  | max 512 chars |
| `email` | string |  | max 128 chars |
| `websites` | string[] |  | max 2 items |
| `vertical` | string |  |  |
| `profile_picture_handle` | string |  | A Resumable Upload handle (Meta's body). PUT /profile/photo makes one from a link. |

### Example

```json
{
  "about": "Plants and flowers, delivered same day",
  "websites": [
    "https://luckyshrub.example",
    "https://luckyshrub.example/shop"
  ]
}
```

## Responses

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | Changed at WhatsApp. |  |
| 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` |
| 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": "p5n2y",
  "updated": [
    "about",
    "websites"
  ],
  "profile": {
    "about": "Plants and flowers, delivered same day",
    "websites": [
      "https://luckyshrub.example",
      "https://luckyshrub.example/shop"
    ]
  }
}
```

## 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), [`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), [`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), [`display_name_not_approved`](https://www.app2email.com/docs/api/errors#display_name_not_approved), [`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_cursor`](https://www.app2email.com/docs/api/errors#invalid_cursor), [`invalid_json`](https://www.app2email.com/docs/api/errors#invalid_json), [`invalid_number_in_url`](https://www.app2email.com/docs/api/errors#invalid_number_in_url), [`invalid_profile`](https://www.app2email.com/docs/api/errors#invalid_profile), [`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_upload_error`](https://www.app2email.com/docs/api/errors#media_upload_error), [`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), [`nothing_to_change`](https://www.app2email.com/docs/api/errors#nothing_to_change), [`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), [`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_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), [`required_parameter_missing`](https://www.app2email.com/docs/api/errors#required_parameter_missing), [`sandbox_key`](https://www.app2email.com/docs/api/errors#sandbox_key), [`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_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_paused`](https://www.app2email.com/docs/api/errors#template_paused), [`template_text_too_long`](https://www.app2email.com/docs/api/errors#template_text_too_long), [`too_many_messages_to_recipient`](https://www.app2email.com/docs/api/errors#too_many_messages_to_recipient), [`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), [`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_permission_missing`](https://www.app2email.com/docs/api/errors#whatsapp_permission_missing), [`whatsapp_rate_limit`](https://www.app2email.com/docs/api/errors#whatsapp_rate_limit), [`whatsapp_unavailable`](https://www.app2email.com/docs/api/errors#whatsapp_unavailable)

## Example

```bash
curl -X PATCH "https://api.app2email.com/v1/YOUR_NUMBER/profile" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "about": "Plants and flowers, delivered same day",
  "websites": ["https://luckyshrub.example", "https://luckyshrub.example/shop"]
}'
```

## 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}/profile": {
      "patch": {
        "tags": [
          "Number"
        ],
        "operationId": "updateBusinessProfile",
        "summary": "Change the WhatsApp business profile",
        "description": "Fields left out stay as they are. Meta's own body (with messaging_product, profile_picture_handle) works unchanged.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Number"
          }
        ],
        "responses": {
          "200": {
            "description": "Changed at WhatsApp.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessProfileUpdateResponse"
                },
                "example": {
                  "success": true,
                  "request_id": "p5n2y",
                  "updated": [
                    "about",
                    "websites"
                  ],
                  "profile": {
                    "about": "Plants and flowers, delivered same day",
                    "websites": [
                      "https://luckyshrub.example",
                      "https://luckyshrub.example/shop"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "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"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BusinessProfileUpdate"
              },
              "example": {
                "about": "Plants and flowers, delivered same day",
                "websites": [
                  "https://luckyshrub.example",
                  "https://luckyshrub.example/shop"
                ]
              }
            }
          }
        },
        "x-a2e-scope": "settings:manage",
        "x-a2e-sandbox": "refused",
        "x-a2e-error-codes": [
          "api_key_expired",
          "api_key_number_mismatch",
          "api_key_old_format",
          "api_key_revoked",
          "block_list_busy",
          "block_list_full",
          "block_users_error",
          "block_users_failed",
          "bsuid_not_supported",
          "call_permission_required",
          "display_name_not_approved",
          "insufficient_scope",
          "internal_error",
          "invalid_api_key",
          "invalid_authorization_header",
          "invalid_cursor",
          "invalid_json",
          "invalid_number_in_url",
          "invalid_profile",
          "ip_not_allowed",
          "marketing_disabled_on_cloud_api",
          "marketing_per_user_limit",
          "media_download_error",
          "media_upload_error",
          "messaging_limit_restricted",
          "missing_api_key",
          "nothing_to_change",
          "number_already_verified",
          "number_not_found",
          "outside_24h_window",
          "parameter_value_invalid",
          "plan_not_allowed",
          "rate_limited",
          "recipient_identity_changed",
          "recipient_in_experiment",
          "recipient_is_sender",
          "recipient_not_allowed",
          "recipient_stopped_marketing",
          "recipient_unreachable",
          "register_limit_reached",
          "required_parameter_missing",
          "sandbox_key",
          "service_not_live",
          "template_disabled",
          "template_format_policy",
          "template_not_found",
          "template_not_marketing",
          "template_parameter_count_mismatch",
          "template_parameter_format_mismatch",
          "template_parameter_invalid",
          "template_paused",
          "template_text_too_long",
          "too_many_messages_to_recipient",
          "unsupported_message_type",
          "username_account_not_linked",
          "username_change_limit",
          "username_not_available",
          "username_not_eligible",
          "username_taken",
          "whatsapp_account_locked",
          "whatsapp_account_restricted",
          "whatsapp_connection_problem",
          "whatsapp_error",
          "whatsapp_maintenance",
          "whatsapp_number_not_registered",
          "whatsapp_parameter_error",
          "whatsapp_payment_issue",
          "whatsapp_permission_missing",
          "whatsapp_rate_limit",
          "whatsapp_unavailable"
        ],
        "x-a2e-webhook-events": [],
        "x-a2e-mcp-tool": "update_profile",
        "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."
          }
        }
      },
      "BusinessProfile": {
        "type": "object",
        "properties": {
          "about": {
            "type": "string",
            "maxLength": 139
          },
          "address": {
            "type": "string",
            "maxLength": 256
          },
          "description": {
            "type": "string",
            "maxLength": 512
          },
          "email": {
            "type": "string",
            "maxLength": 128
          },
          "profile_picture_url": {
            "type": "string",
            "description": "Meta's link to the current photo (read only)."
          },
          "websites": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "type": "string"
            }
          },
          "vertical": {
            "type": "string",
            "enum": [
              "ALCOHOL",
              "APPAREL",
              "AUTO",
              "BEAUTY",
              "EDU",
              "ENTERTAIN",
              "EVENT_PLAN",
              "FINANCE",
              "GOVT",
              "GROCERY",
              "HEALTH",
              "HOTEL",
              "NONPROFIT",
              "ONLINE_GAMBLING",
              "OTC_DRUGS",
              "OTHER",
              "PHYSICAL_GAMBLING",
              "PROF_SERVICES",
              "RESTAURANT",
              "RETAIL",
              "TRAVEL"
            ]
          }
        }
      },
      "BusinessProfileUpdate": {
        "type": "object",
        "properties": {
          "about": {
            "type": "string",
            "minLength": 1,
            "maxLength": 139
          },
          "address": {
            "type": "string",
            "maxLength": 256
          },
          "description": {
            "type": "string",
            "maxLength": 512
          },
          "email": {
            "type": "string",
            "maxLength": 128
          },
          "websites": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "type": "string"
            }
          },
          "vertical": {
            "type": "string"
          },
          "profile_picture_handle": {
            "type": "string",
            "description": "A Resumable Upload handle (Meta's body). PUT /profile/photo makes one from a link."
          }
        },
        "description": "Only the fields to change. messaging_product is accepted and ignored."
      },
      "BusinessProfileUpdateResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "request_id": {
            "type": "string",
            "example": "k3x9a"
          },
          "updated": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "profile": {
            "$ref": "#/components/schemas/BusinessProfile"
          }
        },
        "required": [
          "success",
          "request_id"
        ]
      },
      "Component": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "header",
              "body",
              "button",
              "carousel",
              "limited_time_offer"
            ]
          },
          "sub_type": {
            "type": "string",
            "enum": [
              "url",
              "quick_reply",
              "copy_code",
              "flow",
              "catalog",
              "mpm",
              "spm",
              "order_details"
            ],
            "description": "Buttons only."
          },
          "index": {
            "type": "string",
            "example": "0",
            "description": "Buttons only: position of the button in the template, starting at 0."
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Parameter"
            }
          },
          "cards": {
            "type": "array",
            "description": "type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.",
            "items": {
              "type": "object",
              "properties": {
                "card_index": {
                  "type": "integer"
                },
                "components": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Component"
                  }
                }
              }
            }
          }
        }
      },
      "ContactCard": {
        "type": "object",
        "required": [
          "name"
        ],
        "description": "One vCard, as WhatsApp Cloud API.",
        "properties": {
          "name": {
            "type": "object",
            "required": [
              "formatted_name"
            ],
            "properties": {
              "formatted_name": {
                "type": "string",
                "example": "Jane Citizen"
              },
              "first_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string"
              },
              "middle_name": {
                "type": "string"
              },
              "prefix": {
                "type": "string"
              },
              "suffix": {
                "type": "string"
              }
            }
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "example": "CELL"
                },
                "wa_id": {
                  "type": "string"
                }
              }
            }
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "org": {
            "type": "object",
            "properties": {
              "company": {
                "type": "string"
              },
              "department": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            }
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "birthday": {
            "type": "string",
            "example": "1990-01-31"
          }
        }
      },
      "Currency": {
        "type": "object",
        "properties": {
          "fallback_value": {
            "type": "string",
            "example": "$10.50"
          },
          "code": {
            "type": "string",
            "example": "USD"
          },
          "amount_1000": {
            "type": "integer",
            "example": 10500
          }
        }
      },
      "DateTime": {
        "type": "object",
        "properties": {
          "fallback_value": {
            "type": "string",
            "example": "February 25, 2026"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "how_to_fix"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "account_deactivated",
              "account_not_confirmed",
              "account_service_error",
              "account_service_unavailable",
              "api_key_expired",
              "api_key_number_mismatch",
              "api_key_old_format",
              "api_key_revoked",
              "approval_already_resolved",
              "approval_body_too_large",
              "approval_expired",
              "approval_not_found",
              "automation_not_found",
              "background_start_failed",
              "block_list_busy",
              "block_list_full",
              "block_not_found",
              "block_users_error",
              "block_users_failed",
              "booking_cancelled",
              "booking_not_enabled",
              "booking_not_found",
              "booking_slot_taken",
              "broadcast_cancelled",
              "broadcast_not_cancellable",
              "broadcast_not_found",
              "bsuid_not_supported",
              "call_permission_required",
              "caption_not_supported",
              "caption_too_long",
              "catcher_not_found",
              "client_exists",
              "client_not_editable",
              "client_not_found",
              "connection_failed",
              "connection_in_use",
              "connection_not_found",
              "contact_book_error",
              "contact_not_found",
              "conversation_not_found",
              "daily_cap_reached",
              "dataset_not_found",
              "delivery_in_progress",
              "delivery_not_found",
              "display_name_not_approved",
              "duplicate_recipients",
              "email_not_sent",
              "encryption_key_managed",
              "flow_blocked_by_integrity",
              "flow_cannot_publish",
              "flow_json_download_failed",
              "flow_json_not_found",
              "flow_json_too_large",
              "flow_name_taken",
              "flow_not_deletable",
              "flow_not_editable",
              "flow_not_found",
              "flow_not_published",
              "flow_rejected",
              "form_exists",
              "form_has_submissions",
              "form_not_found",
              "form_not_published",
              "free_form_single_recipient",
              "hold_expired",
              "hold_not_found",
              "idempotency_key_reused",
              "idempotency_request_in_progress",
              "idempotency_request_interrupted",
              "insufficient_scope",
              "internal_error",
              "invalid_addons",
              "invalid_analytics_query",
              "invalid_answers",
              "invalid_api_key",
              "invalid_auth_template",
              "invalid_authorization_header",
              "invalid_automation",
              "invalid_base64",
              "invalid_block",
              "invalid_booking",
              "invalid_bsuid",
              "invalid_call_request",
              "invalid_call_settings",
              "invalid_callback_data",
              "invalid_catalog_id",
              "invalid_client_request",
              "invalid_compare_days",
              "invalid_compliance_info",
              "invalid_components",
              "invalid_connection",
              "invalid_contact_email",
              "invalid_contacts",
              "invalid_contacts_message",
              "invalid_conversation_starters",
              "invalid_conversion_events",
              "invalid_coupon",
              "invalid_csv",
              "invalid_cursor",
              "invalid_direction",
              "invalid_display_name",
              "invalid_email",
              "invalid_estimate",
              "invalid_event_type",
              "invalid_events",
              "invalid_flow_categories",
              "invalid_flow_field",
              "invalid_flow_id",
              "invalid_flow_json",
              "invalid_flow_name",
              "invalid_form",
              "invalid_guests",
              "invalid_idempotency_key",
              "invalid_identity_key_hash",
              "invalid_insights_request",
              "invalid_interactive",
              "invalid_json",
              "invalid_keep_old_for_hours",
              "invalid_key_request",
              "invalid_library_filter",
              "invalid_limit",
              "invalid_link",
              "invalid_list",
              "invalid_location",
              "invalid_marketing_api",
              "invalid_media_id",
              "invalid_media_link",
              "invalid_media_type",
              "invalid_member",
              "invalid_months",
              "invalid_note",
              "invalid_number",
              "invalid_number_in_url",
              "invalid_numbers",
              "invalid_oba_request",
              "invalid_onboarding_request",
              "invalid_optimization_spec",
              "invalid_owner",
              "invalid_partner_settings",
              "invalid_payment",
              "invalid_phone",
              "invalid_plan",
              "invalid_poll",
              "invalid_profile",
              "invalid_public_key",
              "invalid_qr_code",
              "invalid_range",
              "invalid_reaction",
              "invalid_recipients",
              "invalid_redirect_url",
              "invalid_reply_to",
              "invalid_segment",
              "invalid_send_at",
              "invalid_series",
              "invalid_service",
              "invalid_setting",
              "invalid_settings",
              "invalid_setup",
              "invalid_slug",
              "invalid_start",
              "invalid_status",
              "invalid_submission",
              "invalid_template_category",
              "invalid_template_components",
              "invalid_template_field",
              "invalid_template_ids",
              "invalid_template_language",
              "invalid_template_name",
              "invalid_template_preview",
              "invalid_test_event",
              "invalid_text",
              "invalid_ticket_check_in",
              "invalid_ticket_code",
              "invalid_ticket_event",
              "invalid_ticket_order",
              "invalid_time",
              "invalid_to",
              "invalid_username",
              "invalid_users",
              "invalid_wait",
              "invalid_webhook_format",
              "invalid_webhook_headers",
              "invalid_webhook_secret",
              "invalid_webhook_url",
              "ip_not_allowed",
              "key_limit_reached",
              "key_limits_unavailable",
              "key_not_found",
              "link_not_found",
              "link_not_usable",
              "list_not_found",
              "marketing_disabled_on_cloud_api",
              "marketing_per_user_limit",
              "marketing_status_lookup_failed",
              "media_delete_failed",
              "media_download_error",
              "media_download_failed",
              "media_lookup_failed",
              "media_lookups_paused",
              "media_not_found",
              "media_too_large",
              "media_type_not_allowed",
              "media_upload_error",
              "media_upload_failed",
              "member_not_found",
              "message_not_found",
              "message_too_old",
              "messaging_limit_restricted",
              "missing_api_key",
              "missing_file",
              "missing_interactive",
              "missing_media",
              "missing_message_id",
              "missing_numbers",
              "missing_template_language",
              "missing_template_name",
              "missing_text",
              "missing_url",
              "monthly_cap_reached",
              "monthly_limit_reached",
              "not_in_instant_sandbox",
              "note_not_found",
              "nothing_to_change",
              "number_already_verified",
              "number_not_found",
              "number_not_live",
              "optin_not_found",
              "outside_24h_window",
              "package_not_found",
              "parameter_value_invalid",
              "partner_closed",
              "partner_service_unavailable",
              "partner_suspended",
              "payment_link_failed",
              "payment_not_found",
              "payment_provider_error",
              "payments_not_connected",
              "plan_already_active",
              "plan_not_allowed",
              "plan_not_available",
              "poll_not_found",
              "profile_photo_failed",
              "qr_code_not_found",
              "range_too_large",
              "rate_limited",
              "reaction_too_old",
              "recipient_identity_changed",
              "recipient_in_experiment",
              "recipient_is_sender",
              "recipient_not_allowed",
              "recipient_not_opted_in",
              "recipient_opted_out",
              "recipient_stopped_marketing",
              "recipient_unreachable",
              "refund_not_possible",
              "register_limit_reached",
              "request_log_unavailable",
              "request_not_found",
              "request_too_large",
              "required_parameter_missing",
              "route_not_found",
              "sandbox_key",
              "sandbox_recipient",
              "sandbox_unavailable",
              "schedule_failed",
              "segment_and_recipients",
              "segment_empty",
              "segment_exists",
              "segment_not_found",
              "send_at_in_past",
              "send_at_too_far",
              "service_not_live",
              "shop_changed",
              "shop_failed",
              "shop_invalid",
              "shop_limit",
              "shop_not_enabled",
              "shop_not_found",
              "shop_not_ready",
              "shop_not_tracked",
              "shop_order_problems",
              "shop_payment_failed",
              "shop_sku_taken",
              "slug_taken",
              "stage_not_allowed",
              "submission_not_found",
              "submit_not_enabled",
              "submit_not_ready",
              "template_already_exists",
              "template_archive_failed",
              "template_category_locked",
              "template_compare_unavailable",
              "template_delete_failed",
              "template_disabled",
              "template_format_policy",
              "template_insights_confirm_required",
              "template_insights_not_enabled",
              "template_insights_unavailable",
              "template_language_not_found",
              "template_language_required",
              "template_limit_reached",
              "template_lookup_failed",
              "template_name_reserved",
              "template_not_approved",
              "template_not_editable",
              "template_not_found",
              "template_not_marketing",
              "template_parameter_count_mismatch",
              "template_parameter_format_mismatch",
              "template_parameter_invalid",
              "template_parameters_invalid",
              "template_paused",
              "template_rejected",
              "template_sample_media_failed",
              "template_text_too_long",
              "template_unarchive_failed",
              "test_event_too_large",
              "text_too_long",
              "ticket_check_in_not_found",
              "ticket_code_not_found",
              "ticket_date_not_found",
              "ticket_event_not_found",
              "ticket_event_not_publishable",
              "ticket_limit_reached",
              "ticket_not_allowed",
              "ticket_not_found",
              "ticket_order_not_found",
              "ticket_seat_not_available",
              "ticket_type_not_found",
              "tickets_not_enabled",
              "tickets_not_on_sale",
              "tickets_sold_out",
              "to_and_recipients",
              "too_late",
              "too_many_catchers",
              "too_many_invites",
              "too_many_messages_to_recipient",
              "too_many_numbers",
              "too_many_recipients",
              "too_many_segments",
              "too_many_signups",
              "too_many_templates",
              "too_many_tests",
              "too_many_webhooks",
              "unsupported_content_type",
              "unsupported_message_type",
              "username_account_not_linked",
              "username_change_limit",
              "username_not_available",
              "username_not_eligible",
              "username_taken",
              "voice_needs_ogg_opus",
              "waitlist_not_found",
              "waitlist_not_offered",
              "waitlist_not_set_up",
              "webhook_not_found",
              "webhook_url_in_use",
              "whatsapp_account_locked",
              "whatsapp_account_restricted",
              "whatsapp_connection_problem",
              "whatsapp_error",
              "whatsapp_flow_failed",
              "whatsapp_maintenance",
              "whatsapp_number_not_registered",
              "whatsapp_parameter_error",
              "whatsapp_payment_issue",
              "whatsapp_permission_missing",
              "whatsapp_rate_limit",
              "whatsapp_unavailable"
            ],
            "description": "Stable error code, safe to use in your own logic."
          },
          "message": {
            "type": "string",
            "description": "What is wrong, in plain words."
          },
          "how_to_fix": {
            "type": "string",
            "description": "What to change to make the request work."
          },
          "documentation_url": {
            "type": "string",
            "example": "https://www.app2email.com/docs/api/errors#template_not_found",
            "description": "Where this error is explained."
          },
          "is_retriable": {
            "type": "boolean",
            "description": "true: the same request can work later without a change (limits, caps, trouble on our side or WhatsApp's, a request with the same Idempotency-Key still running)."
          },
          "retry_after_seconds": {
            "type": "integer",
            "description": "How long to wait before trying again, when known (also the Retry-After header)."
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Extra information, eg the problems found, available templates or languages."
          },
          "example_request": {
            "$ref": "#/components/schemas/SendTemplateRequest"
          },
          "whatsapp_error": {
            "$ref": "#/components/schemas/WhatsAppError"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "request_id": {
            "type": "string",
            "example": "kxrkf",
            "description": "Quote this when contacting support."
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "FreeFormMedia": {
        "type": "object",
        "description": "Give exactly one of: link, data or id. 'filename' is shown to the recipient for documents.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/photo.jpg",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media (or uploaded to WhatsApp for this number)."
          },
          "filename": {
            "type": "string",
            "example": "invoice.pdf",
            "description": "Needed with 'data' for documents."
          },
          "mime_type": {
            "type": "string",
            "example": "application/pdf",
            "description": "Optional. The type is detected from the file where possible."
          },
          "caption": {
            "type": "string",
            "maxLength": 1024,
            "example": "Your parcel",
            "description": "Optional text under the image, video or document."
          }
        }
      },
      "FreeFormText": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "body": {
            "type": "string",
            "example": "Thanks, it arrives on Friday.",
            "description": "The text. Up to 4096 characters."
          },
          "preview_url": {
            "type": "boolean",
            "default": false,
            "description": "true: show a preview of a link in the text."
          }
        }
      },
      "Interactive": {
        "type": "object",
        "required": [
          "type",
          "action"
        ],
        "description": "WhatsApp's interactive object. type button: action.buttons, up to 3 reply buttons (title up to 20 characters; the shortcut \"buttons\": [\"Confirm\", \"Change\"] works too). type list: action.button (the text that opens the list) and action.sections with rows (up to 10 rows in all; a row can be a plain title). type cta_url: action.parameters {display_text, url}. header: text (60 characters), or image / video / document (link, data or id) for button and cta_url. body.text up to 1024 characters, footer.text up to 60. Also (WhatsApp Cloud API's objects): carousel (action.cards: 2 to 10, image or video header, one URL button or quick replies each; or product cards {card_index, type: 'product', action: {product_retailer_id, catalog_id}}), location_request_message, request_contact_info, flow (action.parameters: flow_message_version '3', flow_id or flow_name, flow_cta), product and product_list (a connected catalog), catalog_message, call_permission_request and voice_call (Calling), address_message (India; optional text header), order_details and order_status (payments). The fixed action.name of a kind is filled in when left out.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "button",
              "list",
              "cta_url",
              "carousel",
              "location_request_message",
              "request_contact_info",
              "flow",
              "product",
              "product_list",
              "catalog_message",
              "call_permission_request",
              "voice_call",
              "address_message",
              "order_details",
              "order_status"
            ]
          },
          "header": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "type": "text",
              "text": "Booking"
            }
          },
          "body": {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "maxLength": 1024,
                "example": "Confirm your booking for Friday 10:00?"
              }
            }
          },
          "footer": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "maxLength": 60
              }
            }
          },
          "action": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "buttons": [
                {
                  "type": "reply",
                  "reply": {
                    "id": "yes",
                    "title": "Confirm"
                  }
                },
                {
                  "type": "reply",
                  "reply": {
                    "id": "no",
                    "title": "Change"
                  }
                }
              ]
            }
          }
        }
      },
      "Language": {
        "type": "object",
        "required": [
          "code"
        ],
        "description": "Required when the template exists in more than one language.",
        "properties": {
          "code": {
            "type": "string",
            "example": "en",
            "description": "Template language code, eg 'en', 'en_US', 'nl'."
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "type": "string",
            "example": "-33.8688"
          },
          "longitude": {
            "type": "string",
            "example": "151.2093"
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          }
        }
      },
      "LocationContent": {
        "type": "object",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "example": -33.8568
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "example": 151.2153
          },
          "name": {
            "type": "string",
            "example": "Sydney Opera House"
          },
          "address": {
            "type": "string",
            "example": "Bennelong Point, Sydney NSW 2000"
          }
        }
      },
      "Media": {
        "type": "object",
        "description": "Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/photo.jpg",
            "description": "Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
          },
          "id": {
            "type": "string",
            "description": "A media id already uploaded to WhatsApp for this number."
          },
          "filename": {
            "type": "string",
            "example": "invoice.pdf",
            "description": "Shown to the recipient for documents. Also helps detect the file type."
          },
          "mime_type": {
            "type": "string",
            "example": "application/pdf",
            "description": "Optional. The type is detected from the file where possible."
          }
        }
      },
      "Parameter": {
        "type": "object",
        "required": [
          "type"
        ],
        "description": "One value. Set 'type' and the matching field, eg {\"type\":\"text\",\"text\":\"John\"} or {\"type\":\"image\",\"image\":{\"link\":\"https://...\"}}.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "video",
              "document",
              "location",
              "currency",
              "date_time",
              "payload",
              "coupon_code",
              "action",
              "product",
              "limited_time_offer"
            ]
          },
          "parameter_name": {
            "type": "string",
            "description": "For templates with NAMED placeholders, eg 'first_name' for {{first_name}}."
          },
          "text": {
            "type": "string",
            "description": "type 'text'. No new lines, tabs or more than 4 spaces in a row."
          },
          "image": {
            "$ref": "#/components/schemas/Media"
          },
          "video": {
            "$ref": "#/components/schemas/Media"
          },
          "document": {
            "$ref": "#/components/schemas/Media"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "date_time": {
            "$ref": "#/components/schemas/DateTime"
          },
          "payload": {
            "type": "string",
            "description": "type 'payload': quick reply button payload."
          },
          "coupon_code": {
            "type": "string",
            "description": "type 'coupon_code': copy code button value."
          },
          "action": {
            "type": "object",
            "additionalProperties": true,
            "description": "type 'action': flow / catalog button data, as WhatsApp Cloud API."
          },
          "product": {
            "type": "object",
            "properties": {
              "product_retailer_id": {
                "type": "string"
              },
              "catalog_id": {
                "type": "string"
              }
            },
            "description": "type 'product': a product header."
          },
          "limited_time_offer": {
            "type": "object",
            "properties": {
              "expiration_time_ms": {
                "type": "integer",
                "example": 1767225600000
              }
            },
            "description": "type 'limited_time_offer': when the offer ends (ms since 1970)."
          }
        }
      },
      "ReactionContent": {
        "type": "object",
        "required": [
          "message_id",
          "emoji"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
            "description": "A message the contact sent, up to 30 days old."
          },
          "emoji": {
            "type": "string",
            "example": "👍",
            "description": "One emoji. \"\" removes your reaction."
          }
        }
      },
      "Recipient": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "One number, with country code."
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            },
            "description": "Only what differs for this number, eg its body values. The rest comes from template.components."
          },
          "recipient_identity_key_hash": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional: this contact's identity_key_hash (see the request's)."
          }
        }
      },
      "SendTemplateRequest": {
        "type": "object",
        "description": "A WhatsApp message in the format of WhatsApp Cloud API (Meta's exact body works unchanged): a template (type 'template', the default, any time), or within 24 hours of the contact's last message a free-form text, image, video, document, audio, sticker, location, contacts, reaction or interactive message. Meta's mark-read body {messaging_product, status: 'read', message_id, typing_indicator?} marks a message as read. Give 'to' or 'recipients' (templates only).",
        "properties": {
          "messaging_product": {
            "type": "string",
            "enum": [
              "whatsapp"
            ],
            "description": "Optional. Always 'whatsapp'."
          },
          "recipient_type": {
            "type": "string",
            "enum": [
              "individual"
            ],
            "description": "Optional. Always 'individual'."
          },
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "Recipient's WhatsApp number with country code. Digits only is best (spaces, '+', '-' are removed). Several recipients: separate the numbers with commas, eg \"61412345678,61498765432\" (semicolons and new lines work too), or send a JSON array of numbers. Each number gets its own message, and the response lists the result per number in 'results'. A free-form message (not 'template') goes to one number. A business-scoped user id (eg 61.AbC123, from from_user_id) is accepted as it is."
          },
          "recipient": {
            "type": "string",
            "example": "61.AbC123xyz",
            "description": "Optional, instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'."
          },
          "segment": {
            "type": "string",
            "example": "VIP, consented",
            "description": "Optional, app2email only, instead of 'to' / 'recipients': the id or name of a saved segment (GET /segments). Templates only. Each contact's named template parameters without a value are filled from its custom_fields ('name' from the contact's name). Recorded as a broadcast."
          },
          "type": {
            "type": "string",
            "enum": [
              "template",
              "text",
              "image",
              "video",
              "document",
              "interactive",
              "audio",
              "sticker",
              "location",
              "contacts",
              "reaction"
            ],
            "default": "template",
            "description": "'template' (default): an approved template. Otherwise a free-form message within the 24 hour window; the field of the same name holds it. Left out with status 'read': mark as read."
          },
          "interactive": {
            "$ref": "#/components/schemas/Interactive",
            "description": "type 'interactive': reply buttons, a list, or a URL button."
          },
          "template": {
            "$ref": "#/components/schemas/Template"
          },
          "text": {
            "$ref": "#/components/schemas/FreeFormText",
            "description": "type 'text': the message."
          },
          "image": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'image': link, data+filename or id, and an optional caption."
          },
          "video": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'video': link, data+filename or id, and an optional caption."
          },
          "document": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'document': link, data+filename or id, and an optional caption."
          },
          "reply_to": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
            "description": "Optional, free-form only: the message_id of one of the contact's messages, quoted by this one. Meta's 'context': {\"message_id\": ...} works too."
          },
          "send_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-02T09:00:00+11:00",
            "description": "Optional, templates only: send later. ISO 8601 with a time zone ('Z' or '+11:00'), 1 minute to 29 days ahead. The answer is HTTP 202 with status 'scheduled'."
          },
          "campaign_name": {
            "type": "string",
            "maxLength": 100,
            "example": "October newsletter",
            "description": "Optional, app2email only. Several numbers in 'to' (or 'recipients'): the name of the broadcast this list is recorded as (Activity Log under Broadcasts). Default \"API: <template name>\". Not used for one number."
          },
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Recipient"
            },
            "description": "Optional, app2email only, instead of 'to': each number with its own values. Each entry's components replace the shared template.components of the same type (a button: the same index). Every number is checked before anything is sent."
          },
          "dry_run": {
            "type": "boolean",
            "default": false,
            "description": "Optional, app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything."
          },
          "background": {
            "type": "boolean",
            "default": false,
            "description": "Optional, app2email only. true: answer HTTP 202 once everything is checked and the media uploaded, then send. Progress: broadcast.status_url (GET /v1/{number}/broadcasts/{code}) or the broadcast.completed webhook event."
          },
          "audio": {
            "$ref": "#/components/schemas/AudioContent",
            "description": "type 'audio'."
          },
          "sticker": {
            "$ref": "#/components/schemas/StickerContent",
            "description": "type 'sticker'."
          },
          "location": {
            "$ref": "#/components/schemas/LocationContent",
            "description": "type 'location'."
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactCard"
            },
            "description": "type 'contacts': 1 to 20 cards."
          },
          "reaction": {
            "$ref": "#/components/schemas/ReactionContent",
            "description": "type 'reaction'."
          },
          "context": {
            "type": "object",
            "properties": {
              "message_id": {
                "type": "string"
              }
            },
            "description": "Meta's form of reply_to."
          },
          "callback_data": {
            "type": "string",
            "maxLength": 512,
            "example": "order-1234",
            "description": "Optional. Sent to WhatsApp as biz_opaque_callback_data; back as data.callback_data in this message's message.status events. Meta's own field name works too."
          },
          "recipient_identity_key_hash": {
            "type": "string",
            "maxLength": 200,
            "example": "DF2lS5v2W6x=",
            "description": "Optional, one recipient (per number: in recipients[]): delivered only while the contact's identity key has this hash (message.received data.identity_key_hash); else message.failed, 137000 recipient_identity_changed. Needs PUT /settings/identity-check."
          },
          "marketing_api": {
            "type": "string",
            "enum": [
              "auto",
              "cloud_api",
              "mm_api"
            ],
            "description": "Optional, MARKETING templates: the path for this send (true = mm_api, false = cloud_api). Default: the number's setting messages.marketing_route (auto)."
          },
          "product_policy": {
            "type": "string",
            "enum": [
              "CLOUD_API_FALLBACK",
              "STRICT"
            ],
            "description": "Optional, Marketing Messages API only: STRICT = no fallback to the Cloud API. Default CLOUD_API_FALLBACK."
          },
          "message_activity_sharing": {
            "type": "boolean",
            "description": "Optional, Marketing Messages API only: share read and click activity with Meta for this message."
          },
          "status": {
            "type": "string",
            "enum": [
              "read"
            ],
            "description": "Meta's mark-read body: 'read' with message_id (no type)."
          },
          "message_id": {
            "type": "string",
            "description": "Meta's mark-read body: the received message."
          },
          "typing_indicator": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "text"
                ]
              }
            },
            "description": "Meta's mark-read body: also show the typing indicator."
          }
        }
      },
      "StickerContent": {
        "type": "object",
        "description": "WebP only: up to 100 KB static, 500 KB animated. No caption.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media."
          },
          "filename": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          }
        }
      },
      "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>"
      }
    }
  }
}
```

