Send a WhatsApp message: template, or free-form reply
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).
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270
Headers
-
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.
e.g.order-1234-shipped
Body application/json required
- messaging_product string
Always 'whatsapp'.
whatsapp - recipient_type string
Always 'individual'.
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.
e.g.61412345678 - recipient string
Instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'.
e.g.61.AbC123xyz - segment string
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.
e.g.VIP, consented -
'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.
templatetextimagevideodocumentinteractiveaudiostickerlocationcontactsreaction - interactive object
type 'interactive': reply buttons, a list, or a URL button.
5 fields
-
buttonlistcta_urlcarousellocation_request_messagerequest_contact_infoflowproductproduct_listcatalog_messagecall_permission_requestvoice_calladdress_messageorder_detailsorder_status - e.g.
{"type":"text","text":"Booking"} - body object
1 fields
- e.g.
Confirm your booking for Friday 10:00?
-
- e.g.
{"buttons":[{"type":"reply","reply":{"id":"yes","title":"Confirm"}},{"type":"re…
-
- template object
3 fields
-
Exact name of an APPROVED template.
e.g.order_update - language object
Required when the template exists in more than one language.
1 fields
-
Template language code, eg 'en', 'en_US', 'nl'.
e.g.en
-
- components object[]
Values for the template's placeholders and media. Leave out for templates without parameters.
5 item fields
-
headerbodybuttoncarousellimited_time_offer - sub_type string
Buttons only.
urlquick_replycopy_codeflowcatalogmpmspmorder_details - index string
Buttons only: position of the button in the template, starting at 0.
e.g.0 - parameters object[]
14 item fields
-
textimagevideodocumentlocationcurrencydate_timepayloadcoupon_codeactionproductlimited_time_offer - parameter_name string
For templates with NAMED placeholders, eg 'first_name' for {{first_name}}.
- text string
type 'text'. No new lines, tabs or more than 4 spaces in a row.
- image object
Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.
5 fields
- link string (uri)
Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id already uploaded to WhatsApp for this number.
- filename string
Shown to the recipient for documents. Also helps detect the file type.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf
- video object
Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.
5 fields
- link string (uri)
Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id already uploaded to WhatsApp for this number.
- filename string
Shown to the recipient for documents. Also helps detect the file type.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf
- document object
Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.
5 fields
- link string (uri)
Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id already uploaded to WhatsApp for this number.
- filename string
Shown to the recipient for documents. Also helps detect the file type.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf
- location object
- currency object
3 fields
- fallback_value stringe.g.
$10.50 - code stringe.g.
USD - amount_1000 integere.g.
10500
- date_time object
1 fields
- fallback_value stringe.g.
February 25, 2026
- payload string
type 'payload': quick reply button payload.
- coupon_code string
type 'coupon_code': copy code button value.
-
type 'action': flow / catalog button data, as WhatsApp Cloud API.
- product object
type 'product': a product header.
2 fields
- product_retailer_id string
- catalog_id string
- limited_time_offer object
type 'limited_time_offer': when the offer ends (ms since 1970).
1 fields
- expiration_time_ms integere.g.
1767225600000
-
- cards object[]
type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.
2 item fields
- card_index integer
- components object[]
-
-
- text object
type 'text': the message.
2 fields
-
The text. Up to 4096 characters.
e.g.Thanks, it arrives on Friday. -
true: show a preview of a link in the text.
-
- image object
type 'image': link, data+filename or id, and an optional caption.
6 fields
- link string (uri)
Public http(s) URL. app2email downloads the file and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id from POST /media (or uploaded to WhatsApp for this number).
- filename string
Needed with 'data' for documents.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf -
Optional text under the image, video or document.
e.g.Your parcel
- video object
type 'video': link, data+filename or id, and an optional caption.
6 fields
- link string (uri)
Public http(s) URL. app2email downloads the file and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id from POST /media (or uploaded to WhatsApp for this number).
- filename string
Needed with 'data' for documents.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf -
Optional text under the image, video or document.
e.g.Your parcel
- document object
type 'document': link, data+filename or id, and an optional caption.
6 fields
- link string (uri)
Public http(s) URL. app2email downloads the file and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id from POST /media (or uploaded to WhatsApp for this number).
- filename string
Needed with 'data' for documents.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf -
Optional text under the image, video or document.
e.g.Your parcel
- reply_to string
Free-form only: the message_id of one of the contact's messages, quoted by this one. Meta's 'context': {"message_id": ...} works too.
e.g.wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA= - send_at string (date-time)
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'.
e.g.2026-11-02T09:00:00+11:00 -
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.
e.g.October newsletter - recipients object[]
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.
3 item fields
-
One number, with country code.
e.g.61412345678 - components object[]
Only what differs for this number, eg its body values. The rest comes from template.components.
5 item fields
-
headerbodybuttoncarousellimited_time_offer - sub_type string
Buttons only.
urlquick_replycopy_codeflowcatalogmpmspmorder_details - index string
Buttons only: position of the button in the template, starting at 0.
e.g.0 - parameters object[]
14 item fields
-
textimagevideodocumentlocationcurrencydate_timepayloadcoupon_codeactionproductlimited_time_offer - parameter_name string
For templates with NAMED placeholders, eg 'first_name' for {{first_name}}.
- text string
type 'text'. No new lines, tabs or more than 4 spaces in a row.
- image object
Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.
5 fields
- link string (uri)
Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id already uploaded to WhatsApp for this number.
- filename string
Shown to the recipient for documents. Also helps detect the file type.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf
- video object
Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.
5 fields
- link string (uri)
Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id already uploaded to WhatsApp for this number.
- filename string
Shown to the recipient for documents. Also helps detect the file type.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf
- document object
Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.
5 fields
- link string (uri)
Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp.
e.g.https://example.com/photo.jpg - data string (byte)
The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted.
- id string
A media id already uploaded to WhatsApp for this number.
- filename string
Shown to the recipient for documents. Also helps detect the file type.
e.g.invoice.pdf - mime_type string
The type is detected from the file where possible.
e.g.application/pdf
- location object
- currency object
3 fields
- fallback_value stringe.g.
$10.50 - code stringe.g.
USD - amount_1000 integere.g.
10500
- date_time object
1 fields
- fallback_value stringe.g.
February 25, 2026
- payload string
type 'payload': quick reply button payload.
- coupon_code string
type 'coupon_code': copy code button value.
-
type 'action': flow / catalog button data, as WhatsApp Cloud API.
- product object
type 'product': a product header.
2 fields
- product_retailer_id string
- catalog_id string
- limited_time_offer object
type 'limited_time_offer': when the offer ends (ms since 1970).
1 fields
- expiration_time_ms integere.g.
1767225600000
-
- cards object[]
type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.
2 item fields
- card_index integer
- components object[]
-
-
This contact's identity_key_hash (see the request's).
-
-
app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything.
-
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'.
6 fields
- link string (uri)
Public http(s) URL. app2email downloads the file and uploads it to WhatsApp.
- data string (byte)
The file, base64 encoded.
- id string
A media id from POST /media.
- filename string
- mime_type string
- voice boolean
true: a voice message (play button, transcript). Ogg with the OPUS codec only; app2email does not convert.
- sticker object
type 'sticker'.
- location object
type 'location'.
- contacts object[]
type 'contacts': 1 to 20 cards.
7 item fields
-
6 fields
- e.g.
Jane Citizen - first_name string
- last_name string
- middle_name string
- prefix string
- suffix string
-
- phones object[]
- emails object[]
- addresses object[]
- org object
3 fields
- company string
- department string
- title string
- urls object[]
- birthday stringe.g.
1990-01-31
-
- reaction object
type 'reaction'.
2 fields
-
A message the contact sent, up to 30 days old.
e.g.wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA= -
One emoji. "" removes your reaction.
e.g.👍
-
- context object
Meta's form of reply_to.
1 fields
- message_id string
-
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.
e.g.order-1234 -
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.
e.g.DF2lS5v2W6x= - marketing_api string
MARKETING templates: the path for this send (true = mm_api, false = cloud_api). Default: the number's setting messages.marketing_route (auto).
autocloud_apimm_api - product_policy string
Marketing Messages API only: STRICT = no fallback to the Cloud API. Default CLOUD_API_FALLBACK.
CLOUD_API_FALLBACKSTRICT - message_activity_sharing boolean
Marketing Messages API only: share read and click activity with Meta for this message.
- status string
Meta's mark-read body: 'read' with message_id (no type).
read - message_id string
Meta's mark-read body: the received message.
- typing_indicator object
Meta's mark-read body: also show the typing indicator.
1 fields
- type string
text
Responses
- Idempotent-Replayed string
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Fields
- success booleane.g.
true - request_id stringe.g.
kxrkf - message_id string
WhatsApp message id.
e.g.wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA= - status string
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).
acceptedpartially_acceptedfailedqueuedscheduleddry_runpending_approval - sandbox boolean
true: a sandbox key simulated the send; nothing went to WhatsApp (message ids start with wamid.SANDBOX.).
- approval object
status pending_approval only.
5 fields
- id stringe.g.
apr_a1b2c3d4e5f6g7h8 - url string
The dashboard page to approve or reject it.
- expires string (date-time)
- recipients integer
- key string
-
status pending_approval only: what was held (recipients, template, text).
- type string
Free-form replies: the message type. Templates: 'template'.
templatetextimagevideodocumentinteractiveaudiostickerlocationcontactsreaction - from stringe.g.
4976659348270 - to stringe.g.
61412345678 - window_closes_at string (date-time)
Free-form replies: when the 24 hour window closes (after the contact's last message).
- scheduled_for string (date-time)
send_at only: when the send starts (UTC).
- scheduled integer
send_at only: how many messages are scheduled.
- template object
- text string
The message text with your values filled in.
- media string
The header media sent, if any.
- conversation_url string
Conversation history page on app2email.com.
- note string
- broadcast object
Several numbers in 'to' only: the broadcast this list is recorded as.
4 fields
- name stringe.g.
October newsletter - code string
- report_url string
The broadcast's report page on app2email.com, with delivered/read counts per number.
- status_url string
GET it (with your API key) for the broadcast's status and the result per number.
- recipients integer
Several numbers in 'to' only: how many different numbers were given.
- accepted integer
Several numbers only: how many messages WhatsApp accepted.
- failed integer
Several numbers only: how many were not sent (see results).
- results object[]
Several numbers only: one entry per number, in the order given.
12 item fields
- to stringe.g.
61412345678 - success boolean
- message_id string
WhatsApp message id, when accepted.
- status string
accepted - text string
This number's message text, when the numbers had different values ('recipients').
- conversation_url string
- error object
Why this number was not sent, eg recipient_opted_out, monthly_limit_reached, recipient_unreachable.
9 fields
-
Stable error code, safe to use in your own logic.
account_deactivatedaccount_not_confirmedaccount_service_erroraccount_service_unavailableapi_key_expiredapi_key_number_mismatchapi_key_old_formatapi_key_revokedapproval_already_resolvedapproval_body_too_largeapproval_expiredapproval_not_foundautomation_not_foundbackground_start_failedblock_list_busyblock_list_fullblock_not_foundblock_users_errorblock_users_failedbooking_cancelledbooking_not_enabledbooking_not_foundbooking_slot_takenbroadcast_cancelledbroadcast_not_cancellablebroadcast_not_foundbsuid_not_supportedcall_permission_requiredcaption_not_supportedcaption_too_longcatcher_not_foundclient_existsclient_not_editableclient_not_foundconnection_failedconnection_in_useconnection_not_foundcontact_book_errorcontact_not_foundconversation_not_found -
What is wrong, in plain words.
-
What to change to make the request work.
- documentation_url string
Where this error is explained.
e.g.https://www.app2email.com/docs/api/errors#template_not_found - is_retriable boolean
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 integer
How long to wait before trying again, when known (also the Retry-After header).
-
Extra information, eg the problems found, available templates or languages.
- example_request object
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).
Fields: as the request body - whatsapp_error object
WhatsApp's (Meta's) own error, when the error came from WhatsApp.
5 fields
- code integere.g.
132000 - message string
- details string
- type string
- fbtrace_id string
-
- would_send boolean
Dry run only.
-
Dry run only: the exact message WhatsApp would get.
- whatsapp_status string
- contacts object[]
- sent_via string
cloud_apimm_api
- error object
Several numbers only, when none were sent: the first number's error.
Fields: as results.error - queued integer
Background send (HTTP 202): how many messages will be sent.
- skipped integer
Background send: how many numbers are skipped (listed in results, eg Do Not Call list).
- dry_run boolean
Dry run only: true.
- would_send integer
Dry run only: how many messages would be sent.
- would_skip integer
Dry run only: how many numbers would be skipped (see results).
- messages_left_this_month integer
Dry run only: messages left this billing month (the plan limit covers outgoing WhatsApp + outgoing emails).
- broadcast_name string
Dry run of a list: the name the broadcast would get.
- whatsapp_status string
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.
acceptedheld_for_quality_assessmentpaused - contacts object[]
WhatsApp's contacts[]: the wa_id and business-scoped user_id it resolved.
- sent_via string
MARKETING templates: the path used (cloud_api = /messages, mm_api = the Marketing Messages API). Dry run: the path it would take.
cloud_apimm_api - whatsapp_edge string
Dry run of a template: the WhatsApp endpoint the message would go to.
messagesmarketing_messages
Errors
- 400 The request is malformed (missing or invalid fields, query parameters or times).
- 401 Missing, invalid, revoked or expired API key.
- 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.
- 404 The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was 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.
- 413 The request or the media file is too large.
- 415 The body is not JSON.
- 422 The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window).
- 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.
- 500 Unexpected error on app2email's side.
- 502 WhatsApp (Meta) returned an error or could not be reached.
- 503 app2email's connection to the WhatsApp account needs attention, or the request log is not available right now.